Error Handling
Comprehensive guide to handling API errors in Bootspring.
Error Response Format
All errors follow a consistent JSON format:
Loading code block...
HTTP Status Codes
| Status | Description |
|---|---|
| 400 | Bad Request - Invalid request body or parameters |
| 401 | Unauthorized - Missing or invalid authentication |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 409 | Conflict - Resource already exists |
| 422 | Unprocessable Entity - Validation failed |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Server-side error |
| 502 | Bad Gateway - Upstream service error |
| 503 | Service Unavailable - Temporarily unavailable |
Error Codes Reference
Authentication Errors (401)
| Code | Message |
|---|---|
unauthorized | Missing or invalid authentication token |
token_expired | The authentication token has expired |
token_revoked | The authentication token has been revoked |
invalid_api_key | The API key is invalid or inactive |
api_key_expired | The API key has expired |
Permission Errors (403)
| Code | Message |
|---|---|
forbidden | You don't have permission to access this resource |
insufficient_scope | Token lacks required scope |
tier_required | This feature requires a higher tier |
quota_exceeded | You've exceeded your plan's quota |
Validation Errors (400, 422)
| Code | Message |
|---|---|
invalid_request | The request body is invalid |
validation_failed | One or more fields failed validation |
missing_field | A required field is missing |
invalid_field | A field has an invalid value |
invalid_json | The request body is not valid JSON |
Resource Errors (404, 409)
| Code | Message |
|---|---|
not_found | The requested resource was not found |
already_exists | A resource with this identifier already exists |
deleted | The resource has been deleted |
Rate Limiting Errors (429)
| Code | Message |
|---|---|
rate_limited | Too many requests, please slow down |
concurrent_limit | Too many concurrent requests |
Server Errors (5xx)
| Code | Message |
|---|---|
internal_error | An internal server error occurred |
service_unavailable | The service is temporarily unavailable |
upstream_error | An upstream service returned an error |
timeout | The request timed out |
Handling Errors
JavaScript/TypeScript
Loading code block...
Python
Loading code block...
Validation Error Details
When validation fails, the details array provides specific information:
Loading code block...
Field Validation Codes
| Code | Description |
|---|---|
required | Field is required |
invalid_type | Field has wrong type |
invalid_email | Not a valid email |
invalid_url | Not a valid URL |
string_length | String length out of bounds |
number_range | Number out of range |
array_max_length | Array too long |
invalid_enum | Value not in allowed list |
pattern_mismatch | Value doesn't match pattern |
Retry Strategies
Exponential Backoff
Loading code block...
Circuit Breaker
Loading code block...
Error Logging
Include the request_id when reporting issues:
Loading code block...
Debugging
Request Headers
Include these headers for debugging:
Loading code block...
Debug Mode Response
With X-Debug: true, responses include additional information:
Loading code block...