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

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).
paymentUrlType must be "web" or "qr"	Typo or unsupported value.	Use exactly web (iframe / browser) or qr.
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 [email protected] 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.