Errors

The canonical error envelope, HTTP status mapping, and idiomatic handling per language.

Every Qeet ID API error uses the same canonical envelope — an error object with a stable machine code, a human message, and optional detail / request_id:

JSON

{
  "error": {
    "code": "unauthorized",
    "message": "authentication required",
    "detail": "missing or invalid Authorization header",
    "request_id": "req_01HXG…"
  }
}

It's nested under `error`

The envelope is { "error": { "code", "message" } } — not a flat error string. Read the machine value from error.code. The request_id matches the X-Request-Id response header.

HTTP status mapping

Status	Meaning
`400`	Malformed request.
`401`	Missing or invalid authentication.
`403`	Authenticated but not permitted.
`404`	Resource doesn't exist.
`409`	Conflict (e.g. duplicate).
`422`	Validation error.
`429`	Rate-limited / locked out. See `Retry-After`.
`5xx`	Server error — retry idempotent calls with backoff.

Common codes

`error.code`	When
`unauthorized`	Missing/invalid token or API key.
`forbidden`	RBAC/policy denied the action.
`not_found`	Resource ID doesn't exist.
`conflict`	Uniqueness/state conflict.
`validation_failed`	Request body failed validation.
`rate_limited`	Rate limit or account lockout hit.

Handling errors

TypeScript

import { QeetidError, RateLimitError } from "@qeetid/sdk";

try {
  await qeetid.users.get(id);
} catch (e) {
  if (e instanceof RateLimitError) await wait(e.retryAfterSeconds);
  else if (e instanceof QeetidError) console.error(e.code, e.requestId);
  else throw e;
}

var apiErr *qeetidsdk.Error
if errors.As(err, &apiErr) {
  switch {
  case apiErr.IsRateLimited(): // apiErr.RetryAfterSeconds
  case apiErr.IsNotFound():
  case apiErr.IsUnauthorized():
  }
}

Python

from qeetid import QeetidError, RateLimitError

try:
    qeetid.users.get(id)
except RateLimitError as e:
    sleep(e.retry_after_seconds)
except QeetidError as e:
    log(e.code, e.request_id)

Retry guidance

Status	Retry?	Strategy
`5xx` (idempotent)	Yes	Exponential backoff.
`429`	Yes	Honor `Retry-After`.
Other `4xx`	No	Surface to the caller.

The SDKs already implement this — 429 and idempotent 5xx are retried with backoff, honoring Retry-After.

HTTP status mapping

Common codes

Handling errors

Retry guidance

On this page