> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-resolve-a-400-validationerror.md).

# How do I resolve a 400 ValidationError?

A **400 ValidationError** means the request JSON failed Bead’s schema or business-rule checks.\
The response body always tells you **which field** failed and **why**—fix that field and retry.

### 1 — Read the error object

```json
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "ValidationError",
  "message": "customer.address2 is required when customer is present",
  "field":   "customer.address2",
  "code":    "MISSING_FIELD"
}
```

| Property    | Meaning                                                          |
| ----------- | ---------------------------------------------------------------- |
| **field**   | JSON path that failed                                            |
| **code**    | Machine-readable reason (`MISSING_FIELD`, `INVALID_VALUE`, etc.) |
| **message** | Human explanation                                                |

### 2 — Most common causes & fixes

| Error message                                                       | Why it happens                                                       | How to fix                                                                 |
| ------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `customer.firstName is required…` (or any other customer sub-field) | You sent some fields in `customer`, so **all nine** become required. | Either supply the missing fields **or** omit the entire `customer` object. |
| `requestedAmount must be > 0`                                       | Amount is zero or negative.                                          | Send a positive decimal number (e.g., `100.00`).                           |
| `merchantId not found`                                              | ID doesn’t belong to the authenticated terminal.                     | Double-check you’re using the correct `merchantId` for this terminal.      |
| `webhookUrls must be an array of https URLs`                        | Single string or non-HTTPS link.                                     | Wrap in `["https://…"]` and use HTTPS.                                     |
| `redirectUrl must be https`                                         | URL is http\:// or malformed.                                        | Change to `https://…` or omit if not needed.                               |

### 3 — Debug checklist

1. **Validate JSON** – Paste into jsonlint.com to catch commas, quotes, etc.
2. **Check types** – Numbers without quotes, strings in quotes, arrays in `[ ]`.
3. **Match enum values** – Use exact casing (`completed`, `web`, etc.).
4. **Use the latest OpenAPI spec** – Download from the “Download OpenAPI” page.
5. **Log the full request & response** – Keep sanitized copies so you can diff changes.

### 4 — Testing fixes quickly

* **Sandbox loop** – Retry the corrected request against `https://api.test.devs.beadpay.io` until you get **201 Created** (or **200 OK**).
* **Postman or cURL** – Great for rapid iterations—copy/paste from your code, tweak, resend.
* **Schema validators** – Use tools like AJV (Node.js) or Pydantic (Python) locally with the OpenAPI schema to catch issues before hitting the API.

### 5 — When to contact support

If the error message is unclear or you believe the value **is** valid, email [**developers@bead.xyz**](mailto:developers@bead.xyz) with:

* The **full response body** (mask credentials)
* The **request body** you sent (mask credentials)
* Terminal ID and timestamp of the call

We’ll reproduce and clarify the validation rule.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-resolve-a-400-validationerror.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.