Failed requests return an appropriate HTTP status code together with a machine-readable error code. Error messages are written to guide the developer, not to be shown to end users.
Error response shape
All errors use the same envelope: success becomes false and the error object carries a code, a message and optional details.
{
"success": false,
"error": {
"code": "insufficient_credits",
"message": "Kredi bakiyeniz bu istek için yeterli değil.",
"details": { "required": 20, "balance": 4 }
}
}Status codes
| HTTP | Error code | Meaning |
|---|---|---|
| 400 | bad_request |
The request body could not be parsed or is not in the expected JSON shape. |
| 401 | unauthenticated |
The Authorization header is missing, or the key is invalid or revoked. |
| 402 | insufficient_credits |
The credit balance or monthly quota is not sufficient for this request. |
| 403 | plan_forbidden |
This endpoint is outside the scope of your current plan. |
| 404 | not_found |
The requested endpoint or resource was not found. |
| 422 | validation_failed |
Parameters failed validation; per-field details are listed in the details object. |
| 429 | rate_limited |
The per-minute rate limit was exceeded. Wait for the duration in the Retry-After header. |
| 500 | server_error |
An unexpected server error. No credit is charged and the request may be retried. |
Retry strategy
Retry 429 and 5xx responses up to three times with exponential backoff. Do not retry 4xx responses other than 429 — they will keep failing until the request is corrected.