Error Handling

The Nevatal API uses standard HTTP status codes and returns structured error responses.

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request — Invalid parameters or validation error
`401`	Unauthorized — Missing or invalid API key
`403`	Forbidden — API key lacks required scope
`404`	Not Found — Resource doesn’t exist
`409`	Conflict — Resource already exists or state conflict
`422`	Unprocessable Entity — Valid JSON but business rule violation
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Something went wrong on our end

Error response format

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Patient document number is required"
}

Validation errors

When a request fails validation, the response includes details about which fields are invalid:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "phone",
      "message": "Phone number must be at least 10 digits"
    }
  ]
}

Rate limiting

When rate limited, check the Retry-After header for the number of seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Best practices

Always check status codes

Don’t assume every response is successful. Check the HTTP status code before processing the body.

Implement retry logic

For 429 and 5xx errors, implement exponential backoff retry logic.

Log error responses

Log the full error response body for debugging. The message field is human-readable.

Getting Started

Core Concepts

Error Handling

Error Handling

HTTP Status Codes

Error response format

Validation errors

Rate limiting

Best practices

​Error Handling

​HTTP Status Codes

​Error response format

​Validation errors

​Rate limiting

​Best practices

Error Handling

HTTP Status Codes

Error response format

Validation errors

Rate limiting

Best practices