> For the complete documentation index, see [llms.txt](https://docs.neobanc.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neobanc.com/errors.md).

# Errors

All errors return a JSON body with a consistent shape:

```json
{
  "error": "Validation failed",
  "details": [
    {
      "path": ["amount"],
      "message": "Expected number, received string"
    }
  ],
  "timestamp": "2026-04-01T12:00:00.000Z",
  "endpoint": "/api/public/create-payment"
}
```

`details` is only present when there is structured context to share — for validation errors it contains the individual field issues.

## Status codes

| Code  | Meaning                                                            | How to handle                                                                                          |
| ----- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `400` | Validation failed or the request body is malformed                 | Inspect `details` for the offending fields; fix and resend. Not retryable as-is.                       |
| `401` | Missing, invalid, deactivated, or under-scoped API token           | Check the `Authorization` header and the token's permission scopes in the dashboard.                   |
| `409` | A request with the same `Idempotency-Key` is still being processed | Wait briefly and retry with the **same** key — you'll receive the original response once it completes. |
| `500` | Something failed on Neobanc's side                                 | Safe to retry with the same `Idempotency-Key`. If persistent, contact support.                         |

## Idempotency

`POST /create-payment` accepts an optional `Idempotency-Key` header (any string up to 255 characters, scoped to your token) so you can safely retry after a timeout without creating a duplicate payment:

* Retrying with the **same key and same body** replays the original response, marked with an `Idempotency-Replayed: true` header.
* Reusing a key with a **different body** returns `400` ("This Idempotency-Key has already been used for a different request").
* A retry that races the original request returns `409` — back off and retry.

Generate a fresh key (e.g. a UUID) per logical payment, persist it alongside your payment intent, and reuse it for all retries of that payment.

## Failed payments are not HTTP errors

A payment that is accepted but later rejected by the biller (e.g. invalid account number) returns `200` at creation and fails asynchronously — you learn about it via the `payment.failed` [webhook](/api-reference/webhooks.md) or `POST /payment-history`, not an HTTP error. Validate account numbers upfront with `POST /payees/validate-account` to catch most of these before creating the payment.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.neobanc.com/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.