Errors
The API uses conventional HTTP status codes and a consistent error envelope. Codes in the 4xx range indicate a problem with the request; 5xx codes indicate a problem on our side.
Error format
Every error response contains a machine-readable code, a human-readable message and — when relevant — the parameter at fault plus a request_id to reference in support tickets.
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "temperature must be between 0 and 2, got 3.5",
"param": "temperature",
"request_id": "req_8f4b21c9d0"
}
}Status codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed JSON or missing required fields. |
| 401 | authentication_error | Missing, revoked or malformed API key. |
| 403 | permission_denied | Key lacks the required scope, or the feature isn't on your plan. |
| 404 | not_found | Resource doesn't exist or belongs to another workspace. |
| 409 | conflict | Concurrent modification — re-fetch and retry with fresh state. |
| 422 | parameter_invalid | Well-formed request with semantically invalid values. |
| 422 | content_policy_violation | Input or requested output violates the acceptable use policy. |
| 429 | rate_limit_exceeded | Too many requests or tokens — honor Retry-After. |
| 429 | insufficient_credits | Monthly credits exhausted; top up or upgrade to continue. |
| 500 | server_error | Unexpected failure on our side — safe to retry with backoff. |
| 503 | overloaded | Capacity is saturated; retry with backoff or switch to -flash. |
Retry guidance
- Retryable:
429,500,503— use exponential backoff with jitter (see rate limits). - Not retryable:
400,401,403,422— fix the request first; identical retries will fail identically. - Generation requests accept an
Idempotency-Keyheader, making network-level retries safe against double billing.
Catching errors in the SDK
import Tapotik from "@tapotik/sdk";
try {
await client.chat.completions.create({ model: "tapotik-2-pro", messages });
} catch (err) {
if (err instanceof Tapotik.RateLimitError) {
// 429 — SDK already retried twice; queue and slow down
} else if (err instanceof Tapotik.AuthenticationError) {
// 401 — rotate or re-provision the key
} else if (err instanceof Tapotik.APIError) {
console.error(err.status, err.code, err.requestId);
} else {
throw err; // network failure, bug, etc.
}
}Include the
request_id when contacting support — it lets us trace a request end-to-end across the edge network in seconds.