Error response format and HTTP status codes.
All errors follow a consistent shape:
{
"error": {
"code": "error_code",
"message": "Human-readable description.",
"details": {}
}
}The code field is machine-readable and stable. The message field is human-readable and may change. The details field provides additional context where applicable.
| HTTP Status | Code | Description |
|---|---|---|
| 400 | invalid_request | Malformed JSON body |
| 401 | unauthorized | Missing API key or session token |
| 401 | invalid_api_key | Key format invalid or key not found |
| 401 | invalid_credentials | Wrong email or password |
| 402 | insufficient_credits | No credits remaining |
| 403 | origin_not_allowed | Origin header missing or not in allowed list |
| 403 | email_not_verified | Email not yet verified |
| 404 | not_found | Device or resource not found |
| 409 | email_already_registered | Account with this email already exists |
| 422 | validation_error | Request body failed schema validation |
| 429 | rate_limited | Rate limit exceeded |
| 503 | service_unavailable | Pricing data temporarily unavailable |
When the request body fails schema validation (422), the details field includes an array of issues:
{
"error": {
"code": "validation_error",
"message": "Validation failed.",
"details": {
"issues": [
{ "field": "devices.1.qty", "message": "Expected positive integer" }
]
}
}
}Each issue includes the field path (dot-notation) and a description of the problem.