# 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.