Error Handling

The Prepzo API uses consistent error formats across all endpoints. Every response tells you exactly what went wrong and how to fix it.

Response Format

All API responses follow the same structure:

// Success
{
  "success": true,
  "data": { ... },
  "meta": { "total": 50, "limit": 50, "offset": 0, "has_more": false },
  "errors": null
}

// Error
{
  "success": false,
  "data": null,
  "meta": null,
  "errors": [
    {
      "code": "not_found",
      "message": "Candidate not found",
      "field": null
    }
  ]
}

HTTP Status Codes

Error Codes

Validation Errors

Validation errors include a field property pointing to the problematic field:

{
  "success": false,
  "data": null,
  "errors": [
    {
      "code": "validation_error",
      "message": "email is required",
      "field": "email"
    }
  ]
}

Best Practices

• Always check success: Don't rely solely on HTTP status codes
• Handle 429s gracefully: Implement exponential backoff with the Retry-After header
• Log error codes: The code field is stable and safe for programmatic handling
• Don't parse messages: The message field is human-readable and may change
• Retry 500s: Server errors are typically transient. Retry with backoff.
• Don't retry 4xx: Client errors (except 429) won't succeed on retry without changes