The HTTP status codes and error codes the Kawaa API returns, what each one means, and how to handle it.
HTTP status codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 202 | Accepted - Batch or file job queued |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 402 | Payment Required - Out of credits, or your card was declined for a plan change |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Endpoint doesn't exist |
| 413 | Payload Too Large - Request body exceeds the limit |
| 429 | Too Many Requests - Rate limited |
| 500 | Server Error - Try again later |
| 503 | Service Unavailable - Retry with backoff |
| 504 | Gateway Timeout - The free checker on kawaa.com sends it when a check takes too long. The API answers a slow verification with 200 and pending, so a 504 from the API is a gateway or server failure: retry |
Error response format
Errors use the same envelope as successful responses, with success: false and the detail under error. Branch on error.code rather than matching error.message, which is free text. Quote error.request_id when contacting support.
{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid email format",
"request_id": "89eac422-6b08-4d18-986b-ab3e1ed3aa57"
}
}Common error codes
| HTTP | error.code | Solution |
|---|---|---|
| 400 | BAD_REQUEST | Check the request body and email format |
| 401 | UNAUTHORIZED | Send a valid key in X-API-Key |
| 401 | API_KEY_SUSPENDED / API_KEY_REVOKED | Suspended: restore billing and the same key works again, or issue a new key. Revoked: issue a new key in the dashboard, or connect an app that signed in again (the error message names the two rarer cases with another remedy) |
| 402 | INSUFFICIENT_CREDITS | Add more credits |
| 402 | PAYMENT_REQUIRED | Your card was declined for a plan change, or your bank wants you to confirm the payment, and nothing was changed yet. Update your payment method in Settings → Billing and try again, or, if your bank asked, use Confirm payment on the billing page (the response's confirmation_url) |
| 403 | FORBIDDEN | Access denied for a reason the codes below do not cover |
| 403 | INSUFFICIENT_SCOPE | The key is valid but not scoped for this route; issue one that is (an app connected by signing in: connect it again asking for the scope as well as the ones it already has, unless the message says a connected app can never be given it; then use an API key with every scope the message names, or have the account owner act in the dashboard) |
| 403 | PLAN_UPGRADE_REQUIRED | Your plan does not include this feature; no key of any scope reaches it |
| 403 | PLAN_LIMIT_EXCEEDED | You are at your plan’s limit for this feature; delete one or upgrade |
| 404 | NOT_FOUND | Check the path and any resource id |
| 413 | BATCH_SIZE_EXCEEDED | The batch or file holds more addresses than one job takes on your plan, the file is over 50 MB, or the file took too long to read (the message says so). Split it; a file upload has the same per-job limit as a batch. A request body over about 6 MB never reaches Kawaa: the gateway answers 413 itself with only the message "Request Entity Too Large" and no error.code, so read the status; nothing is run or charged |
| 429 | RATE_LIMITED | Back off using Retry-After |
| 500 | INTERNAL_ERROR | Retry; contact support with the request id |
| 503 | SERVICE_UNAVAILABLE | Retry with exponential backoff |
| 504 | GATEWAY_TIMEOUT | Sent by the free checker on kawaa.com when a check takes too long; retry. The API answers a slow verification with 200 and pending instead |