Skip to main content

​
Error Handling

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

​
HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad Request — Invalid parameters or validation error
401Unauthorized — Missing or invalid API key
403Forbidden — API key lacks required scope
404Not Found — Resource doesn’t exist
409Conflict — Resource already exists or state conflict
422Unprocessable Entity — Valid JSON but business rule violation
429Too Many Requests — Rate limit exceeded
500Internal 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

1

Always check status codes

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

Implement retry logic

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

Log error responses

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