Error response format
| Field | Description |
|---|---|
code | Structured error code: BLUM-{HTTP_STATUS}-{SEQUENCE} |
message | Human-readable description of the error |
Error code categories
| Prefix | HTTP Status | Category |
|---|---|---|
BLUM-400-* | 400 Bad Request | Validation failures, malformed requests |
BLUM-401-* | 401 Unauthorized | Authentication errors |
BLUM-403-* | 403 Forbidden | Authorization/permission errors |
BLUM-404-* | 404 Not Found | Resource doesn’t exist or not accessible |
BLUM-409-* | 409 Conflict | Duplicate resource or state conflict |
BLUM-422-* | 422 Unprocessable | Business rule violation |
BLUM-429-* | 429 Too Many Requests | Rate limit exceeded |
BLUM-500-* | 500 Internal Error | Server-side error |
Common errors
Authentication (401)
| Code | Message | Resolution |
|---|---|---|
BLUM-401-001 | Missing authorization | Include Authorization: Basic <credentials> header |
BLUM-401-002 | Malformed credentials | Verify Base64 encoding of API_KEY:API_SECRET |
BLUM-401-003 | Invalid credentials | Check key and secret are correct and not revoked |
Validation (400)
| Code | Message | Resolution |
|---|---|---|
BLUM-400-001 | Generic validation error | Check the message for specific field issues |
BLUM-400-002 | Missing required field | Include all required fields in the request |
BLUM-400-003 | Invalid field format | Match expected types and formats (dates as ISO 8601, etc.) |
Not Found (404)
| Code | Message | Resolution |
|---|---|---|
BLUM-404-001 | Resource not found | Verify the ID exists and belongs to your tenant |
Rate Limiting (429)
| Code | Message | Resolution |
|---|---|---|
BLUM-429-001 | Rate limit exceeded | Implement backoff; check Retry-After header |
Rate limits
| Environment | Limit |
|---|---|
| Sandbox | 10 requests/second per key pair |
| Production | 25 requests/second per key pair |
Retry strategy
Implement exponential backoff with jitter for retryable errors (429, 500, 502, 503, 504):
400, 401, 403, 404, or 422 errors — these indicate client-side issues that won’t resolve on retry.
HTTP status codes
| Code | Meaning | Retryable |
|---|---|---|
200 | Success (GET, PUT, DELETE) | N/A |
201 | Created (POST) | N/A |
400 | Bad request | No |
401 | Unauthorized | No (fix credentials) |
403 | Forbidden | No (check permissions) |
404 | Not found | No |
409 | Conflict | No (resolve conflict) |
422 | Unprocessable | No (fix business logic) |
429 | Rate limited | Yes (with backoff) |
500 | Server error | Yes (with backoff) |