Build

Error Handling

Understand error responses, HTTP status codes, and how to handle errors in the Lev API.

Updated March 2026

Error Format

All error responses include a request_id for correlation with support and a structured error object:

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": {
    "code": "NOT_FOUND",
    "message": "Deal with id 999 not found"
  }
}

The request_id matches the value logged in usage tracking, so it can be referenced when contacting support.

Status Codes

Code	Meaning	When
`200`	OK	Successful read or update
`201`	Created	Successful resource creation
`400`	Bad Request	Invalid request body, missing required fields, malformed query parameters
`401`	Unauthorized	Missing, invalid, or expired authentication token
`403`	Forbidden	Valid token but insufficient permissions
`404`	Not Found	Resource doesn't exist or isn't accessible to the authenticated user
`409`	Conflict	Idempotency conflict (different request body with same idempotency key)
`422`	Unprocessable Entity	Valid JSON but semantically invalid (e.g., invalid enum value)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

Common Errors

Missing authentication

{
  "request_id": "...",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Resource not found

Returns 404 both when a resource doesn't exist and when the authenticated user doesn't have access to it. This prevents information leakage about resource existence.

{
  "request_id": "...",
  "error": {
    "code": "NOT_FOUND",
    "message": "Deal with id 999 not found"
  }
}

Validation error

{
  "request_id": "...",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid value for field 'loan_type': must be one of [acquisition, refinance, construction, ...]"
  }
}

Rate limited

{
  "request_id": "...",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}