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.

Example: No Authorization header, expired key, malformed key.

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.

Example: Key restricted to specific models or IP addresses.

404not_found

The requested model or resource does not exist.

Example: Invalid model ID, unknown endpoint.

429rate_limit_error

You have exceeded your rate limit. Retry after the specified delay.

Example: Too many requests per minute or per second.

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.

Example: Maintenance window, capacity limits.

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.