Error Handling
Understand API errors with clear guidance on HTTP status codes and machine-readable response bodies.
The Blazelock API uses standard HTTP response codes to indicate whether a request succeeded or failed and returns machine-readable error payloads so your integration can react predictably.
In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate that the request failed based on the provided input or context. Codes in the 5xx range indicate an error on Blazelock's side.
Error Response Format
Error responses are JSON objects. Every error response includes a machine-readable code and a human-readable message.
You can use the Content-Language header to provide a two-letter ISO language code. We return the message in that language. See Response Language for more information.
| Field | Type | Description |
|---|---|---|
code | string | Stable, machine-readable error identifier. |
message | string | Human-readable explanation of the problem. |
validation | object | Present on validation errors. Maps field names or field paths to arrays of error messages. |
Example error response:
{
"code": "unauthenticated",
"message": "You must be authenticated to perform this action."
}Common Error Types
These are the most common error cases your integration should handle:
| HTTP-Status | Error-Code | Description |
|---|---|---|
401 | unauthenticated | The request is missing a valid API key. Verify that you send Authorization: Bearer <api-key>. See Authentication. |
403 | forbidden | The request is authenticated, but the action is not allowed. |
404 | resource_not_found | The requested resource could not be found or is not accessible in the current context. |
422 | validation | One or more request fields failed validation. See Validation Errors. |
429 | throttle_requests | The request was rate limited. See Rate Limits. |
500 | uncaught_error | An unexpected server error occurred while processing the request. |
Validation Errors
For validation errors, we provide detailed information about each failed validation.
The message field contains a general summary of the validation failure. The validation field contains the detailed errors as an object whose keys are the affected field names or field paths and whose values are arrays of error messages.
For nested input and array-based input, field paths are returned in dot notation, for example users.0.email.
Validation error texts also follow the Content-Language header. See Response Language for more information.
Example validation response:
{
"code": "validation",
"message": "The my_field_name field must not be greater than 255 characters.",
"validation": {
"my_field_name": [
"The my_field_name field must not be greater than 255 characters."
]
}
}Endpoint-Specific Errors
This page explains the general error behavior of the API.
Some endpoints can return additional errors depending on their specific validation rules or behavior. For those cases, check the documentation of the individual endpoint in the API reference.
Best Practices
- Check for Status Codes: Always check HTTP status codes first to determine broad error categories.
- Extract Error Details: Parse the error object for detailed information.
- Implement Retries Carefully: Only retry on 5xx errors or when explicitly advised.
- Log Complete Errors: Log the full error response for debugging purposes.