Error Handling
Understanding API error codes and how to handle them in your application.
Error Response Format
All API errors follow a consistent JSON structure to make handling them easier:
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {
// Additional context (optional)
}
}
}HTTP Status Codes
The Cappers API uses standard HTTP status codes to indicate the success or failure of requests:
| Status Code | Meaning |
|---|---|
| 200 | Success - Request completed successfully |
| 400 | Bad Request - Invalid request parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 403 | Forbidden - API key valid but lacks permission |
| 404 | Not Found - Endpoint or resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Something went wrong on our end |
| 503 | Service Unavailable - API temporarily offline for maintenance |
Common Error Codes
Authentication Errors
MISSING_API_KEY401No API key was provided in the request.
Example Response:
{
"error": {
"code": "MISSING_API_KEY",
"message": "No API key provided"
}
}INVALID_API_KEY401The provided API key is invalid or has been revoked.
Example Response:
{
"error": {
"code": "INVALID_API_KEY",
"message": "Invalid API key"
}
}INSUFFICIENT_PERMISSIONS403Your plan doesn't include access to this endpoint.
Example Response:
{
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"message": "Upgrade to Pro plan to access this endpoint"
}
}Rate Limit Errors
RATE_LIMIT_EXCEEDED429You've exceeded your rate limit. Wait before making more requests.
Example Response:
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 45 seconds.",
"retryAfter": 45
}
}Request Errors
INVALID_PARAMETER400One or more request parameters are invalid.
Example Response:
{
"error": {
"code": "INVALID_PARAMETER",
"message": "Invalid parameter: season",
"details": {
"parameter": "season",
"value": "2025",
"expected": "Valid season year (e.g., 2024)"
}
}
}RESOURCE_NOT_FOUND404The requested resource doesn't exist.
Example Response:
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Player with ID 99999 not found"
}
}Server Errors
INTERNAL_ERROR500An unexpected error occurred on our servers.
Example Response:
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An internal error occurred. Please try again later."
}
}SERVICE_UNAVAILABLE503The API is temporarily unavailable for maintenance.
Example Response:
{
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "API is under maintenance. Check status page for updates."
}
}Best Practices
1. Always Check Status Codes
Check the HTTP status code before processing the response body.
const response = await fetch(url, options);
if (!response.ok) {
const error = await response.json();
console.error(`API Error: ${error.error.code}`);
// Handle error appropriately
return;
}
const data = await response.json();
// Process successful response2. Implement Retry Logic
For transient errors (500, 503), implement exponential backoff retry logic.
async function fetchWithRetry(url, options, maxRetries = 3) {
let lastError;
for (let i = 0; i < maxRetries; i++) {
try {
const response = await fetch(url, options);
// Don't retry client errors (4xx)
if (response.status >= 400 && response.status < 500) {
return response;
}
if (response.ok) {
return response;
}
lastError = await response.json();
// Wait before retrying (exponential backoff)
await new Promise(resolve =>
setTimeout(resolve, Math.pow(2, i) * 1000)
);
} catch (error) {
lastError = error;
}
}
throw new Error(`Max retries exceeded: ${lastError}`);
}3. Log Errors for Debugging
Log error details including the error code, message, and request context to help with debugging.
4. Handle Errors Gracefully
Provide user-friendly error messages and fallback behavior in your application.
5. Monitor API Status
Subscribe to our status page for real-time updates on API health and planned maintenance.