Skip to main content

​
Error Codes

The API uses standard HTTP status codes and a consistent JSON error shape. Always check the status code and, when present, the error (and optional message or details) field for details.

​
HTTP Status Codes

CodeMeaningWhen it occurs
200OKRequest succeeded.
400Bad RequestInvalid body, missing required fields, or invalid format (e.g. dataset, model ID).
401UnauthorizedMissing or invalid API key; authentication required.
402Payment RequiredInsufficient balance. Add funds in the dashboard.
403ForbiddenAPI key valid but not allowed for this resource (e.g. key scoped to another model).
404Not FoundModel, job, or resource not found or not active.
429Too Many RequestsRate limit exceeded. See Rate limits.
500Internal Server ErrorUnexpected server error; retry with backoff.
503Service UnavailableBackend or dependency unavailable (e.g. INFRA_API_URL not configured).
504Gateway TimeoutRequest took too long (e.g. inference timeout).

​
Error Response Format

Failed responses return JSON in this shape: 
{
  "error": "Short error description or code",
  "message": "Optional longer message for the client",
  "details": {}
}
Some routes return a nested object: 
{
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED",
    "details": null
  }
}
Use the error (or error.message) and HTTP status code for handling; details may contain extra context when available.

​
Common Errors

​
401 Unauthorized

  • Cause: No Authorization header, or API key invalid/revoked.
  • Fix: Create an API key in the dashboard and send Authorization: Bearer sk_....

​
402 Payment Required

  • Cause: User balance too low for inference or training.
  • Fix: Add funds via the billing/usage section in the dashboard.

​
403 Forbidden

  • Cause: API key is scoped to a specific deployed model and the request targets a different model.
  • Fix: Use a universal API key or the key that matches the requested model.

​
404 Not Found

  • Cause: Model ID not found, model not active, or job ID invalid.
  • Fix: Verify the model is deployed and active, or the job ID exists for your workspace.

​
429 Too Many Requests

  • Cause: Rate limit exceeded for that endpoint and IP.
  • Fix: Wait for the time given in Retry-After and retry; consider batching or reducing concurrency.

​
500 / 503

  • Cause: Server or upstream (e.g. inference backend) error.
  • Fix: Retry with exponential backoff; if persistent, check status or contact support.

​
Next Steps