Error Codes

The Binom Router API uses standard HTTP status codes to indicate the success or failure of an API request. This document provides a comprehensive list of error codes, their meanings, and recommended actions for resolving issues.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": "Additional context about the error",
    "requestId": "unique-request-id-for-tracing",
    "timestamp": "2024-02-07T12:34:56.789Z"
  }
}

HTTP Status Codes

400 Bad Request

Description: The request was malformed or contains invalid parameters.

Common Causes:

• Invalid JSON syntax in request body
• Missing required fields in the request
• Invalid data types or format (e.g., malformed UUID, invalid date format)
• Validation errors for input parameters

Recommended Actions:

1. Verify the request body is valid JSON
2. Check that all required fields are present
3. Validate data types and formats against API documentation
4. Review the details field for specific validation errors

Example:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters",
    "details": "Field 'email' is required and must be a valid email address",
    "requestId": "req_abc123",
    "timestamp": "2024-02-07T12:34:56.789Z"
  }
}

401 Unauthorized

Description: Authentication is required or has failed.

Common Causes:

• Missing or invalid API key
• Expired authentication token
• Incorrect credentials provided
• API key does not have required permissions

Recommended Actions:

1. Ensure your API key is included in the Authorization header
2. Verify the API key is valid and not expired
3. Check that your credentials are correct
4. Contact support if you believe your API key should have access

Example:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "details": "Valid API key must be provided in Authorization header",
    "requestId": "req_def456",
    "timestamp": "2024-02-07T12:34:56.789Z"
  }
}

402 Payment Required

Description: Payment is required to access the requested resource.

Common Causes:

• Subscription plan does not include this feature
• API usage quota has been exceeded
• Account has overdue payments
• Feature requires premium subscription

Recommended Actions:

1. Check your current subscription plan and features
2. Review your API usage statistics
3. Upgrade your subscription plan if needed
4. Contact billing support for payment issues

Example:

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Premium feature access required",
    "details": "This endpoint requires a Premium subscription. Current plan: Basic",
    "requestId": "req_ghi789",
    "timestamp": "2024-02-07T12:34:56.789Z"
  }
}

404 Not Found

Description: The requested resource could not be found.

Common Causes:

• Invalid endpoint URL
• Resource ID does not exist
• Resource has been deleted or moved
• Incorrect HTTP method for the endpoint

Recommended Actions:

1. Verify the endpoint URL is correct
2. Check that the resource ID exists and is valid
3. Ensure you're using the correct HTTP method (GET, POST, PUT, DELETE)
4. Review the API documentation for correct endpoint paths

Example:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": "Route with ID '550e8400-e29b-41d4-a716-446655440000' does not exist",
    "requestId": "req_jkl012",
    "timestamp": "2024-02-07T12:34:56.789Z"
  }
}

429 Too Many Requests

Description: The client has sent too many requests in a given amount of time.

Common Causes:

• Exceeded rate limit for your API key
• Too many concurrent requests
• Burst of requests exceeding allowed threshold

Recommended Actions:

1. Implement exponential backoff in your client
2. Check the Retry-After header for suggested wait time
3. Reduce request frequency
4. Consider upgrading your plan for higher rate limits

Response Headers:

• Retry-After: Number of seconds to wait before retrying
• X-RateLimit-Limit: Maximum requests per time window
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Unix timestamp when the rate limit resets

Example:

{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Rate limit exceeded",
    "details": "Maximum of 1000 requests per hour exceeded. Please retry after 3600 seconds.",
    "requestId": "req_mno345",
    "timestamp": "2024-02-07T12:34:56.789Z"
  }
}

500 Internal Server Error

Description: An unexpected error occurred on the server.

Common Causes:

• Unexpected server-side error
• Database connection failure
• Third-party service outage
• Configuration issue

Recommended Actions:

1. Retry the request after a short delay
2. Check the system status page for ongoing incidents
3. If the error persists, contact support with the requestId
4. Ensure your request is not causing the server error

Example:

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "details": "The server encountered an unexpected condition. Please try again later.",
    "requestId": "req_pqr678",
    "timestamp": "2024-02-07T12:34:56.789Z"
  }
}

503 Service Unavailable

Description: The service is temporarily unavailable due to maintenance or overload.

Common Causes:

• Scheduled maintenance in progress
• Server overload or high traffic
• Database maintenance
• Critical service degradation

Recommended Actions:

1. Check the Retry-After header for estimated availability
2. Review the system status page for maintenance announcements
3. Implement retry logic with exponential backoff
4. Wait before retrying the request

Response Headers:

• Retry-After: Number of seconds to wait before retrying

Example:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable",
    "details": "The service is undergoing scheduled maintenance. Expected to be back in 30 minutes.",
    "requestId": "req_stu901",
    "timestamp": "2024-02-07T12:34:56.789Z"
  }
}

Best Practices for Error Handling

1. Always check the HTTP status code before processing the response body
2. Log error responses including the requestId for debugging
3. Implement retry logic for 429, 500, and 503 errors with exponential backoff
4. Handle rate limiting gracefully by respecting the Retry-After header
5. Validate your requests before sending to avoid 400 errors
6. Monitor your API usage to prevent hitting rate limits
7. Keep your authentication credentials secure and up-to-date

Quick Reference Table