Skip to main content
Our API is designed to return consistent, structured errors that make it easy to debug and recover from issues during development and production.

​
Error types & status codes

The API uses standard HTTP status codes to indicate the success or failure of a request. Errors will always return:
  • An appropriate HTTP status code (4xx or 5xx)
  • A JSON response body containing:
    • status: the HTTP status code
    • error: a human-readable error message
    • support_id: a unique reference ID you can provide to support for debugging
The support_id fields are kept in our systems only up to a week, be sure to reach out to us within that time window or they might get lost.
Example error response:
The support_id is a traceable identifier in the format support_{uuidv7} and is included in every response — successful or not. If you encounter an issue, sharing this ID with our support team helps us investigate quickly and accurately.

​
Common error codes

​
Rate-limiting

If your application sends too many requests in a short period, you may receive a 429 Too Many Requests error. Rate-limiting may be applied by:
  • BitGPT’s infrastructure
  • Cloudflare, our edge network
These responses always include:
  • HTTP status code 429
  • A JSON response with status, error, and support_id
  • Optional Retry-After header or field to indicate when you can try again
Implement retry logic and respect this header to prevent repeated failures.

Rate limits

Check out the rate limit specs, how they work and what you can do to increase them.

​
Best Practices

  • Always check the status and error fields in responses, even for non-200 statuses.
  • Log the support_id for every request and surface it in error reports, this helps us assist you faster.
  • Handle 5xx errors gracefully using retries with exponential backoff.
  • Double-check authentication for 401 and 403 errors, ensure your API key is valid and has the required scopes.
  • Back off properly on 429 rate limit errors, —do not hammer the server.

​
Debugging Tips

  • Use tools like curl, Postman, or HTTP clients with logging to inspect full request/response cycles.
  • Ensure the request is targeting the correct endpoint, using the correct HTTP method (GET, POST, etc.).
  • Validate that your request body matches expected structure and content types (e.g., application/json).
  • Refer to the Authentication and API Keys pages for access-related details.
If you’re still stuck, contact support@bitgpt.xyz and include the support_id shown in the error response to help us resolve the issue quickly.