Quick fixes for the most common Kawaa API errors, 400, 401, 402, 403 and 429, with the cause of each and what to change.
Authentication errors
401 Unauthorized
Cause: Invalid or missing API key
Fix: Check your API key is correct and sent in the X-Api-Key header, or as a Bearer token in the Authorization header
403 Forbidden
Cause: One of several different refusals, named by error.code: the key is not scoped for this route (INSUFFICIENT_SCOPE), your plan does not include the feature (PLAN_UPGRADE_REQUIRED) or is at its limit for it (PLAN_LIMIT_EXCEEDED), or, in a browser, a dashboard sign-in was refused (CROSS_SITE_SESSION_REFUSED) because another website or a page other than the dashboard started the request, or because the request spends credits and was opened outside the dashboard, from a link in a mail app or Slack, a bookmark, or the address bar
Fix: Branch on error.code; only the two plan codes are fixed by upgrading. API authentication lists every 403 and its remedy
Request errors
400 Bad Request
Cause: Invalid email format, a missing or mistyped parameter, or a field the route does not accept
Fix: Read error.message, which names the field, and validate the email format before sending
Rate and quota errors
429 Too Many Requests
Cause: Rate limit exceeded
Fix: Implement backoff and retry, or upgrade plan
402 Payment Required
Cause: Out of credits (INSUFFICIENT_CREDITS), or the payment for a plan change did not go through (PAYMENT_REQUIRED): your card was declined, or your bank wants you to confirm the payment
Fix: For credits, buy a credit pack or upgrade. If your bank wants you to confirm the payment, choose Confirm payment on the billing page (the response's confirmation_url) and confirm it before the time the message names; your new plan starts once it is paid. For a declined card, update your payment method in Settings → Billing, then change plan again