Skip to content
Hayonix

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:

JSON
{
  "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.

StatustypeTypical codeMeaning
400invalid_request_errorinvalid_valueThe request is malformed or a value is not allowed
401authentication_errorinvalid_api_keyMissing, malformed, revoked or expired key
402insufficient_credit_errorinsufficient_credit, spend_limit_reachedOut of credit, or a spend limit is reached
403permission_errorforbidden, organization_suspendedThe key's scopes or the organization's standing do not allow it
404not_found_errornot_found, route_not_foundNo such resource in this project, or no such route
409conflict_erroralready_existsThe resource's current state does not allow this
409conflict_erroridempotency_in_progressA request with this Idempotency-Key is still running
422idempotency_erroridempotency_key_reusedThe key was used with a different request
429quota_exceeded_errorquota_exceededAn organization quota is reached
429rate_limit_errorrate_limitedToo many requests; see retry-after
5xxapi_errorinternal_errorSomething 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:

ClassFor
InvalidRequestError400 (and 422 other than idempotency)
AuthenticationError401
InsufficientCreditError402
PermissionDeniedError403
NotFoundError404
ConflictError409
IdempotencyErrorany Idempotency-Key problem
QuotaExceededError429 quota
RateLimitError429 rate limit
ServerError5xx

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 an Idempotency-Key, are retried after a network failure, a timeout, 408, 409 idempotency_in_progress and 5xx.
  • Every request is retried after a 429 rate limit, because the limiter answers before anything runs. The wait is retry-after when the server sends it.
  • Other POST and PATCH requests 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.