Skip to main content

Onboarding API: errors and status codes

HTTP status codes returned by the onboarding API and how to read validation errors.

Onboarding endpoints return standard HTTP status codes, and validation errors list every failing field in one response.

Status codes

Status

Meaning

What to do

200 / 201

Success

Read the result from data

400

One or more fields failed validation

Fix each path in errorDetails and resend

401

Missing or invalid credentials

Check the JWT or API key, and that it matches the host

409

Conflict, for example a merchant with this legal name already exists

Look up the existing record before retrying

429

Rate limit exceeded

Wait, then retry

500

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.

code

Meaning

invalid_type with received: "undefined"

The field is missing

invalid_type with received: "nan"

A number field got text or nothing

unrecognized_keys

Remove the listed keys from the object at path

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.

Did this answer your question?