Onboarding endpoints return standard HTTP status codes, and validation errors list every failing field in one response.
Status codes
Status | Meaning | What to do |
| Success | Read the result from |
| One or more fields failed validation | Fix each path in |
| Missing or invalid credentials | Check the JWT or API key, and that it matches the host |
| Conflict, for example a merchant with this legal name already exists | Look up the existing record before retrying |
| Rate limit exceeded | Wait, then retry |
| Unexpected server error | Note the time of the call and any request ID header, and contact ValPay support. Check whether the record exists before retrying. |
Validation errors
A 400 lists every problem in errorDetails. Each entry has a path, an array of keys and list positions, and a message:
{
"success": false,
"status": 400,
"message": "Validation of one or more fields failed",
"errorDetails": [
{ "code": "invalid_type", "expected": "object", "received": "undefined",
"path": ["stores", 0, "address"], "message": "Required" },
{ "code": "unrecognized_keys", "keys": ["countryCode"],
"path": ["legalEntity", "organization"], "message": "Unrecognized key(s) in object: 'countryCode'" }
]
}["stores", 0, "address"] means stores[0].address: the address of the first store.
| Meaning |
| The field is missing |
| A number field got text or nothing |
| Remove the listed keys from the object at |
When a whole object is missing, the error names the object but not its fields. After you add it, the next response lists any fields still missing inside it.
