Concepts
Errors and retries
The one error envelope, its types and codes, the SDK error classes, and which failures are retried automatically.
The error envelope
Every error, from the control-plane API and from the inference API alike, has one shape:
{
"error": {
"message": "quota exceeded for pods (limit 3)",
"type": "quota_exceeded_error",
"code": "quota_exceeded",
"param": "pods"
}
}type is the broad class and decides how to react; code is the precise reason, stable enough to branch on; param names the request field or header the error is about, when there is one; message is for people and may change. Every response carries X-Request-Id: quote it when you report a problem.
| Status | type | Typical code | Meaning |
|---|---|---|---|
| 400 | invalid_request_error | invalid_value | The request is malformed or a value is not allowed |
| 401 | authentication_error | invalid_api_key | Missing, malformed, revoked or expired key |
| 402 | insufficient_credit_error | insufficient_credit, spend_limit_reached | Out of credit, or a spend limit is reached |
| 403 | permission_error | forbidden, organization_suspended | The key's scopes or the organization's standing do not allow it |
| 404 | not_found_error | not_found, route_not_found | No such resource in this project, or no such route |
| 409 | conflict_error | already_exists | The resource's current state does not allow this |
| 409 | conflict_error | idempotency_in_progress | A request with this Idempotency-Key is still running |
| 422 | idempotency_error | idempotency_key_reused | The key was used with a different request |
| 429 | quota_exceeded_error | quota_exceeded | An organization quota is reached |
| 429 | rate_limit_error | rate_limited | Too many requests; see retry-after |
| 5xx | api_error | internal_error | Something failed on our side |
SDK error classes
Both SDKs raise one class per type, all subclasses of ApiError, which carries status, type, code, param and the request ID:
| Class | For |
|---|---|
InvalidRequestError | 400 (and 422 other than idempotency) |
AuthenticationError | 401 |
InsufficientCreditError | 402 |
PermissionDeniedError | 403 |
NotFoundError | 404 |
ConflictError | 409 |
IdempotencyError | any Idempotency-Key problem |
QuotaExceededError | 429 quota |
RateLimitError | 429 rate limit |
ServerError | 5xx |
Failures before any answer arrives are NetworkError and RequestTimeoutError. The waiting helpers add WaitTimeoutError (time ran out) and UnexpectedStateError (the resource reached a state it cannot leave for the one you waited for).
import { ApiError, NotFoundError, RateLimitError } from 'hayonix';
try {
await client.pods.get('pod_00000000000000000000000000');
} catch (err) {
if (err instanceof NotFoundError) {
console.log('not found:', err.message);
} else if (err instanceof RateLimitError) {
console.log('slow down; retry after', err.retryAfterSeconds, 's');
} else if (err instanceof ApiError) {
console.log(err.status, err.type, err.code, err.param, 'request', err.requestId);
} else {
throw err;
}
}What is retried
The SDKs and the CLI retry a failure only when doing the request twice cannot do anything twice:
- Safe requests (
GET,PUT,DELETE) and creating requests, which always carry anIdempotency-Key, are retried after a network failure, a timeout,408,409 idempotency_in_progressand5xx. - Every request is retried after a
429rate limit, because the limiter answers before anything runs. The wait isretry-afterwhen the server sends it. - Other
POSTandPATCHrequests are never retried once they may have reached the server, and a quota error is never retried.
Retries back off exponentially with jitter (about 0.5 s, 1 s, 2 s, capped at 8 s). By default a call is retried twice; a server-requested wait longer than 60 seconds is not attempted. Both are client options.
If you write your own client, follow the same rules, and send an Idempotency-Key on every creating request so that a retry is always safe.