Error Codes

ApexApi uses standard HTTP status codes and returns structured error responses.

Error Response Format

All errors return a JSON object with an error field containing the type, message, and HTTP status code.

Error Response

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided. Check that your key starts with 'ak-' and is valid.",
    "code": 401
  }
}

HTTP Status Codes

400invalid_request_error

The request body is malformed or missing required fields.

Example: Missing 'messages' field, invalid JSON, unsupported parameter.

401authentication_error

The API key is missing, invalid, or revoked. An expired key returns code 'api_key_expired'. An unknown agent claim token returns code 'invalid_claim_token'.

Example: No Authorization header, expired key (api_key_expired), malformed key, unknown agent claim token (invalid_claim_token).

402insufficient_credits

Your account does not have enough credits for this request.

Example: Credit balance is zero or below the estimated cost.

403permission_error

The API key does not have permission for this action. Code 'model_not_allowed' means the model is outside the key's (or your organization's) model allowlist. Code 'guardrail_blocked' (type 'invalid_request_error') means a content guardrail in block mode matched the request before any model ran.

Example: Key restricted to specific models (model_not_allowed), IP addresses, or content blocked by a guardrail (guardrail_blocked).

404not_found

The requested model or resource does not exist.

Example: Invalid model ID, unknown endpoint.

429rate_limit_error

A request limit was exceeded. This also covers per-key spend guardrails: 'credit_limit_exceeded' (the key's lifetime credit limit), 'monthly_spend_limit_exceeded' (the key's monthly spend limit), and 'daily_spend_limit_exceeded' (the key's daily spend limit). Retry after the specified delay, or raise the limit on the key. Agent registration has a per-IP daily cap; exceeding it returns code 'agent_register_rate_limited'.

Example: Too many requests, a key's credit/monthly/daily spend limit reached, or agent registration per-IP daily limit exceeded (agent_register_rate_limited).

500internal_error

An unexpected error occurred on our servers.

Example: Server crash, unhandled exception.

502provider_error

The upstream AI provider returned an error.

Example: Provider downtime, model overloaded.

503service_unavailable

The service is temporarily unavailable. Retry with exponential backoff. Code 'spend_check_unavailable' means a configured per-key spend limit could not be verified just now; simply retry.

Example: Maintenance window, capacity limits, or a transient spend-limit check failure (spend_check_unavailable).

Retry Strategy

Use exponential backoff for retryable errors (429, 500, 502, 503). Do not retry client errors (400, 401, 402, 403, 404).

retry.ts

async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error; // Don't retry 4xx errors (except 429)
    }
  }
  throw new Error("Max retries exceeded");
}

Best Practices

1.Always check the error.type field for programmatic error handling.
2.Use exponential backoff with jitter for 429 and 5xx errors.
3.Check the Retry-After header on 429 responses for the recommended wait time.
4.Monitor your credit balance to avoid 402 errors. Enable auto top-up in your dashboard.
5.For 502 errors, the upstream provider may be down. Try a different model or provider.