Error reference

Errors use the same envelope as successful responses, with success: false and an appropriate HTTP status code.

Standard error envelope

{
  "success": false,
  "message": "Human-readable error message",
  "data": null
}

On validation or business errors, data may be a string or null.

For 422 Unprocessable Entity, the API may return FastAPI-style validation details (detail array) instead of the standard envelope. Treat any non-2xx status as an error.

Example error responses

400 Bad Request

{
  "success": false,
  "message": "Profile not found",
  "data": null
}

403 Forbidden

{
  "success": false,
  "message": "Insufficient credits",
  "data": null
}

404 Not Found

{
  "success": false,
  "message": "Resume not found",
  "data": null
}

422 Unprocessable Entity

Validation errors (e.g. missing required field, string too long) may return a body like:

{
  "detail": [
    {
      "loc": ["body", "title"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

429 Too Many Requests

Rate limit responses use the standard error envelope:

{
  "success": false,
  "message": "Too many requests. Please try again later.",
  "data": {
    "error_code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "retry_after": 45
    }
  }
}

Headers include Retry-After (seconds until reset), X-RateLimit-Remaining: 0, and X-RateLimit-Reset (Unix timestamp when the limit resets). For full details and examples, see Rate limiting.

HTTP status codes