Error Handling: Robust API Response Management

Learn how to handle errors gracefully and understand the different error responses. Our comprehensive error codes help you debug and resolve issues quickly.

Error Response Format

All API errors follow a consistent JSON response format with a status code and descriptive message. All error responses contain exactly two fields:

• statusCode (number): HTTP status code indicating the type of error
• message (string): Human-readable error message describing what went wrong

{
  "statusCode": 400,
  "message": "The 'quantity' variable must be at least 1"
}

Note: Error messages use a consistent format for validation errors. Field names are always quoted and follow the pattern: The 'fieldName' variable is required or The 'fieldName' variable must be...

Common Error Responses

400 Bad Request

The request could not be understood or contained invalid parameters.

Example Responses:

{
  "statusCode": 400,
  "message": "The 'region' variable is required"
}

{
  "statusCode": 400,
  "message": "The 'quantity' variable must be at least 1"
}

{
  "statusCode": 400,
  "message": "The 'authType' variable must be one of: 'user' or 'ip'"
}

Common Causes:

• Invalid token format (must be 12 alphanumeric characters)
• Missing required fields in request body (e.g., "The 'field' variable is required")
• Invalid parameter values (e.g., "The 'quantity' variable must be at least 1")
• Invalid field types (e.g., "The 'username' variable must be a string")
• Invalid enum values (e.g., "The 'region' variable must be one of: 'US' or 'EU' or 'AS' or 'AU'")
• Query parameter validation failures
• Invalid date range (startDate after endDate)
• Insufficient stock available for this request

401 Unauthorized

Authentication is required and has failed or has not been provided.

Example Response:

{
  "statusCode": 401,
  "message": "Authentication required"
}

Common Causes:

• Missing Authorization header
• Invalid Basic authentication credentials
• Incorrect username or password
• Malformed Authorization header

403 Forbidden

The server understood the request but refuses to authorize it.

Example Response:

{
  "statusCode": 403,
  "message": "Access denied"
}

Common Causes:

• Insufficient permissions for the requested resource
• Account suspended or inactive
• Token belongs to another reseller
• Rate limit exceeded for this account

404 Not Found

The requested resource could not be found.

Example Response:

{
  "statusCode": 404,
  "message": "Token not found"
}

Example Response:

{
  "statusCode": 404,
  "message": "Resource not found"
}

Common Causes:

• Token does not exist
• Token has been deleted
• Token belongs to another reseller
• Invalid endpoint URL

405 Method Not Allowed

The HTTP method used for the request is not supported for this endpoint.

Example Response:

{
  "statusCode": 405,
  "message": "Method not allowed"
}

Common Causes:

• Sending a POST request to a GET-only endpoint
• Using DELETE on an endpoint that only supports retrieval
• Attempting unsupported HTTP verbs (e.g., PATCH) on token routes

408 Request Timeout

The server did not receive a timely response from an upstream service.

Example Response:

{
  "statusCode": 408,
  "message": "Request timeout"
}

Common Causes:

• Provider API exceeded its response window
• Network instability between Proxy API and the provider
• Long-running operations that surpassed timeout limits

409 Conflict

The request conflicts with the current state of the resource.

Example Response:

{
  "statusCode": 409,
  "message": "Resource already exists"
}

Common Causes:

• Token already exists with the same identifier
• Concurrent modification of the same resource
• Token is currently being processed

429 Too Many Requests

The user has sent too many requests in a given amount of time.

Example Response:

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Please try again later"
}

Common Causes:

• Exceeded API rate limits
• Too many token creation requests
• Excessive stock check requests

500 Internal Server Error

An unexpected error occurred on the server.

Example Response:

{
  "statusCode": 500,
  "message": "Internal server error"
}

Common Causes:

• Database connection issues
• Cache service unavailability
• Unexpected application errors

503 Service Unavailable

The server is temporarily unable to handle the request.

Example Response:

{
  "statusCode": 503,
  "message": "Service temporarily unavailable"
}

Common Causes:

• Database maintenance in progress
• Cache service unavailable
• System overload or maintenance
• External service temporarily unavailable

Validation Error Message Format

All validation errors follow a consistent format to make it easy to identify which field caused the error:

• Required fields: The 'fieldName' variable is required
• Type errors: The 'fieldName' variable must be a string|number|array|boolean
• Enum errors: The 'fieldName' variable must be one of: 'value1' or 'value2'
• Range errors: The 'fieldName' variable must be at least X or The 'fieldName' variable must be at most X
• Length errors: The 'fieldName' variable must be at least X characters or The 'fieldName' variable must be at most X characters
• Array errors: The 'fieldName' array cannot contain more than X items or The 'fieldName' array cannot contain duplicate IP addresses

Field names are always quoted in error messages for clarity.