> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nova.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Nova.Pay API Errors: Status Codes and Response Handling

> A reference for every Nova.Pay HTTP status code and error response shape, with guidance on handling validation errors and transient failures.

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.

```json theme={null}
{
  "errors": [
    "Customer email can't be blank",
    "Payment plan is invalid"
  ]
}
```

<ResponseField name="errors" type="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.
</ResponseField>

<Note>
  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.
</Note>

## Handling Errors

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/authentication) page for details.
  </Step>
</Steps>

<Warning>
  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.
</Warning>


## Related topics

- [Nova.Pay API Authentication: Keys, Hosts & Webhooks](/authentication.md)
- [How to Validate and Apply Discount Coupons in Nova.Pay](/guides/coupons.md)
- [Webhooks API — Handle Payment Gateway Event Callbacks](/api-reference/webhooks.md)
- [Build a Custom Nova.Pay Checkout with AI](/guides/ai-checkout-skill.md)
- [Nova.Pay Payment Methods: Credit Card, Pix, and Boleto](/concepts/payment-methods.md)