Error Handling
The API uses standard HTTP status codes and returns errors as JSON.
Error Format
{
"error": "Description of what went wrong"
}Status Codes
| Code | Meaning |
|---|---|
400 | Bad request - invalid input or missing required fields |
401 | Unauthorized - invalid or missing API key |
402 | Payment required - active subscription and payment method needed (or free-tier limit) |
404 | Not found - resource does not exist |
409 | Conflict - resource is in an incompatible state (e.g., starting a non-pending experiment) |
413 | Payload too large - request body exceeds size limit |
415 | Unsupported media type - invalid content type |
500 | Internal server error |
Validation Errors
When request body validation fails, the error message describes the first validation issue:
{
"error": "Expected string, received number"
}Common Errors
Missing required field:
{ "error": "Required" }Invalid UUID:
{ "error": "Invalid uuid" }State conflict:
{ "error": "Can only update pending experiments" }Billing required (402):
Starting an experiment or creating an agent evaluation that uses platform-managed models requires an active subscription and a payment method on the workspace's organization:
{
"error": "Usage billing and a payment method are required for platform model usage."
}A free organization is also blocked when its owner already owns another free organization:
{
"error": "This account already owns another free organization. Upgrade this organization, or the other free organization, to a paid plan to continue."
}See the full API Reference for endpoint-specific error details.