Error Codes
All API errors return a consistent JSON envelope:
{
"ok": false,
"error": {
"code": "validation_error",
"message": "The email field is required.",
"details": [
{ "field": "email", "message": "This field is required." }
]
}
}
HTTP Status Codes
| Code | Name | Description |
|---|---|---|
| 200 | OK | Request succeeded |
| 201 | Created | Resource created successfully |
| 204 | No Content | Request succeeded (no body) |
| 400 | Bad Request | Invalid request body or parameters |
| 401 | Unauthorized | Missing or invalid authentication token |
| 403 | Forbidden | Insufficient permissions (e.g., analyst trying owner action) |
| 404 | Not Found | Resource does not exist or belongs to another workspace |
| 409 | Conflict | Resource already exists (e.g., duplicate email) |
| 422 | Validation Error | Request body failed validation (see details array) |
| 429 | Rate Limited | Too many requests. See Rate Limits |
| 500 | Internal Error | Server error. Contact support if persistent |
Common Error Codes
| Error Code | Description |
|---|---|
| invalid_credentials | Wrong email or password |
| token_expired | Bearer token has expired. Re-authenticate |
| email_not_verified | Email verification required before login |
| workspace_limit | Maximum workspace count reached |
| node_limit | Node limit reached for current plan |
| subscription_required | Trial expired and no active subscription |
| validation_error | One or more fields failed validation |
| rate_limited | Request rate exceeded. Retry after cooldown |
| resource_not_found | The requested resource does not exist |
| permission_denied | Your role lacks permission for this action |
| duplicate_resource | A resource with this identifier already exists |
| agent_key_invalid | Invalid or revoked agent API key |