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: 
{
  "status": 403,
  "error": "Access denied. You do not have permission to perform this action.",
  "support_id": "support_018ecfc3-bfa6-7b95-a29c-bd8fc3f5b2c6",
  ...other response content
}
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

CodeDescription
400Bad Request – The request was malformed or contained invalid parameters.
401Unauthorized – Authentication failed. Your API key may be missing or incorrect.
403Forbidden – You’re authenticated but don’t have permission to perform the requested action.
404Not Found – The resource you are trying to access does not exist.
406Not Acceptable – The requested response format is not supported (JSON is required).
429Too Many Requests – You’ve exceeded your request quota. Retry after the time specified in the Retry-After header
500Internal Server Error – An unexpected error occurred on our side. These are rare.
503Service Unavailable – The system is temporarily offline (e.g., during maintenance).

​
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 [email protected] and include the support_id shown in the error response to help us resolve the issue quickly.