Nova.Pay API Errors: Status Codes and Response Handling

Nova.Pay follows standard HTTP conventions for signaling the outcome of every request. Successful requests return a 200, 201, or 204 status code with a JSON body (or no body, for 204). When something goes wrong, Nova.Pay returns a 4xx or 5xx status code and, where applicable, a JSON body describing the problem. Designing your integration around these codes will make your error handling predictable and resilient.

HTTP Status Code Reference

Status Code	Meaning	When it occurs
`200 OK`	Successful read or update	The request was valid and the resource was returned or updated.
`201 Created`	Resource successfully created	A new resource (e.g., order, checkout session) was created and its representation is returned in the body.
`204 No Content`	Successful but no body	The request succeeded but there is nothing to return — for example, a payment search that yields no results.
`401 Unauthorized`	Invalid Basic Auth credentials	The Basic Auth credentials supplied to a webhook receiver endpoint are incorrect or missing.
`403 Forbidden`	Host not allowed or invalid API key	The request origin is not in `allowed_hosts`, or the `Authorization` header contains an invalid or missing API key.
`404 Not Found`	Resource does not exist	The requested resource (order, charge link, etc.) could not be found for your account.
`422 Unprocessable Entity`	Validation or business logic error	The request was well-formed but failed validation or a business rule. The response body contains an `errors` array with human-readable messages.
`503 Service Unavailable`	Downstream processing failure	A dependent service (e.g., payment processor or webhook delivery) was temporarily unavailable. Nova.Pay automatically retries failed webhook deliveries on `5xx` responses.

Validation Error Format

When Nova.Pay returns 422 Unprocessable Entity, the response body always contains an errors array. Each item in the array is a human-readable string describing a specific validation failure or business rule violation.

{
  "errors": [
    "Customer email can't be blank",
    "Payment plan is invalid"
  ]
}

errors

string[]

required

An array of one or more human-readable error messages describing why the request was rejected. Present on all 422 responses. Each string corresponds to a distinct validation failure or business rule violation.

The errors array may contain multiple messages in a single response. Display all of them to help your users (or your debugging process) understand everything that needs to be corrected before retrying.

Handling Errors

Follow these steps whenever your integration receives a non-2xx response:

Check the HTTP status code first

Branch your error-handling logic on the status code before inspecting the body. A 503 needs a retry strategy; a 422 needs user-facing feedback; a 403 needs a configuration fix.

Parse the errors array on 422

Deserialize the JSON body and surface every message in the errors array to the end user or your application logs. Do not retry a 422 without first correcting the input — the same request will fail again.

Retry with exponential back-off on 503

Transient failures from downstream services should be retried. Use an exponential back-off strategy (e.g., 1 s → 2 s → 4 s) with a maximum of three to five attempts before surfacing an error to the user. Nova.Pay automatically retries failed webhook deliveries on 5xx responses.

Verify your host and API key on 403

A 403 almost always indicates a configuration problem rather than a transient failure. Check that your request origin appears in your allowed_hosts list, or that your Authorization header contains a valid, active API key. See the Authentication page for details.

Do not silently swallow 4xx errors in your integration. Log the full response body alongside the HTTP status code so that you can diagnose issues quickly — especially 422 responses, which carry actionable detail in the errors array.

Get Started

Concepts

Guides

Nova.Pay API Errors: Status Codes and Response Handling

HTTP Status Code Reference

Validation Error Format

Handling Errors

​HTTP Status Code Reference

​Validation Error Format

​Handling Errors

HTTP Status Code Reference

Validation Error Format

Handling Errors