Skip to main content
Our API returns consistent, structured errors. These errors help you debug and recover from problems in development and in production.

​
Error types & status codes

The API uses standard HTTP status codes to show the success or failure of a request. Errors always return:
  • An applicable HTTP status code (4xx or 5xx)
  • A JSON response body that contains:
    • status: the HTTP status code
    • error: a human-readable error message
    • support_id: a unique reference ID that you can give to support for debugging
Contact us in the week after the error occurs. We keep the support_id fields in our systems only for up to a week. After that time, they can be lost.
Example error response:
The support_id is a traceable identifier in the format support_{uuidv7}. The API includes it in every response, successful or not. If you find a problem, give this ID to our support team. This helps us investigate quickly and accurately.

​
Common error codes

​
Rate limits

If your application sends too many requests in a short period, you can receive a 429 Too Many Requests error. These sources can apply a rate limit:
  • The infrastructure of Prem API
  • Cloudflare, our edge network
These responses always include:
  • The HTTP status code 429
  • A JSON response with status, error, and support_id
  • An optional Retry-After header or field that shows when you can try again
Implement retry logic. Obey this header to prevent repeated failures.
Not every 429 follows this shape. Rate limiting applied further upstream (for example, at the model backend) can return a 429 status with a generic body and no Retry-After header. Branch on the HTTP status code, not the body, and fall back to your own exponential backoff when Retry-After is missing. See Rate limits.

Rate limits

Read the rate limit specifications, how they operate, and how to increase them.

​
Best Practices

  • Always check the status and error fields in responses, also for non-200 statuses.
  • Log the support_id for every request. Show it in error reports. This helps us help you faster.
  • Handle 5xx errors safely with retries and exponential backoff.
  • Check authentication for 401 and 403 errors. Make sure that your API key is valid and has the required scopes.
  • Wait before you retry after 429 rate limit errors. Do not send requests continuously to the server.

​
Tips to debug errors

  • Use tools such as curl, Postman, or HTTP clients with logs to examine the full request and response cycles.
  • Make sure that the request goes to the correct endpoint with the correct HTTP method (GET, POST, etc.).
  • Make sure that your request body matches the expected structure and content types (e.g., application/json).
  • Refer to the Authentication and API Keys pages for details about access.
If the problem continues, contact support@premai.io. Include the support_id from the error response. This helps us solve the problem quickly.

​
SDK error handling

The TypeScript SDK surfaces errors from the attestation gate separately from HTTP API errors. When attestation fails, the SDK throws an AttestationError and exposes helpers to inspect it and get a user-safe message. See Attestation error handling for the full guide.