Error Handling

All API errors follow a standard format with consistent HTTP status codes and structured error responses.

Standard Error Format

All error responses follow this consistent structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { /* Optional additional context */ },
    "field": "field_name" /* Optional field name for validation errors */
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

HTTP Status Codes

Code	Meaning	When It Occurs
200	OK	Request succeeded
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for endpoint
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Service temporarily unavailable

401 Unauthorized

Returned when no API key is provided or the API key is invalid.

HTTP 401

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide a valid API key."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

403 Forbidden

Returned when the API key does not have sufficient permissions for the requested endpoint.

HTTP 403

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "This endpoint requires enterprise tier access. Please upgrade your plan."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

400 Validation Error

Returned when request parameters or body are invalid or missing required fields.

HTTP 400

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "variant_id is required",
    "field": "variant_id"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

429 Rate Limit Exceeded

Returned when you exceed your tier's rate limits. Check your dashboard for current usage.

HTTP 429

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

404 Not Found

Returned when the requested resource (device, variant, etc.) does not exist.

HTTP 404

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Variant not found."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

500 Internal Server Error

Returned when an unexpected error occurs on the server. If this persists, contact support.

HTTP 500

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal server error occurred. Please try again later."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

503 Service Unavailable

Returned when a dependent service (e.g., IMEI provider) is temporarily unavailable.

HTTP 503

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "IMEI lookup service is temporarily unavailable. Please try again later."
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Handling Best Practices

Always check the success field before processing responses
Use the error.code field for programmatic error handling
Display error.message to end users for clarity
Implement exponential backoff for 429 and 503 errors
Log error details including timestamp for debugging
For validation errors, check the field property to identify the problematic parameter
Monitor your rate limit usage in the dashboard to avoid 429 errors