Error Handling

Pixapi returns HTTP status codes and machine-readable error codes. Your app should separate user-correctable errors from transient infrastructure failures.

Error shape

{
  "error": {
    "code": "model_unavailable",
    "message": "The selected model is temporarily unavailable.",
    "request_id": "req_..."
  }
}

Handling categories

Category	Examples	Action
Request errors	invalid_request, model_not_found	Fix request validation.
Auth errors	unauthorized	Ask for a valid API key.
Billing errors	insufficient_credits	Show Credits or Billing.
Policy errors	prompt_rejected	Ask the user to revise input.
Transient errors	rate_limited, model_unavailable	Retry with backoff.

Retry pattern

Use exponential backoff for transient failures.

const delays = [500, 1000, 2000];
for (const delay of delays) {
  const res = await callPixapi();
  if (res.ok) return res;
  if (![429, 500, 503].includes(res.status)) break;
  await new Promise((resolve) => setTimeout(resolve, delay));
}

Request ids

Log request_id when available. Include it when opening a support ticket so the team can trace a failing model call without exposing the original prompt to unrelated systems.