invalid_request: The request failed validation
The body or the parameters did not match the route's schema. Nothing was done.
A body the server refuses before any route runs (JSON that does not parse, an empty JSON body, a wrong media type, or a body that is too large) carries the same code with param body, under the HTTP status the server chose for it (a 4xx, not always 400).
What to do
errorDetail.paramnames the first field that failed. Amounts are decimal strings of integer micro-USD units.
On the wire
HTTP 400, error type invalid_request_error. The body depends on the surface:
- Owner API routes that predate 1.4.0:
{"error": "<message>"}only, unless the client sendsDynamo-Error-Detail: 1; thenerrorDetailis added as below. A refusal before any route runs (theparambodycase) follows the same rule on every owner route. - Newer owner API routes (the 1.4.0 control routes and later, including adoption, terms, main switch, tasks, policies, organisations, recourse, reports, fees, webhooks and payments): the same body with
errorDetail, sent to every client. - Accounts, scoped credentials, list pagination, KYA, card agent programs, ramps (
/owner/v1/ramps…, and the payee off-ramp routes/payee/v1/offramps…), human payments, the developer surfaces (top-ups, widgets, budget links, portal, test fixtures) and the multi-tenant front door:erroris"invalid_request"(not the message), always witherrorDetail. KYA, card agent programs and ramps also senddetail. Pagination'sfixis "limit is 1..100; pass back next_cursor unchanged", and the developer surfaces pointdoc_urlat the matching developers guide. - Payee routes (
/payee/v1/…: destinations, terms offers, tasks, recourse answers; not the off-ramp routes above):{"error": "invalid_request", "detail": "…"}with noerrorDetail.
The detailed owner API body:
{
"error": "invalid … (fail closed)",
"errorDetail": {
"type": "invalid_request_error",
"code": "invalid_request",
"message": "…",
"param": "capUnits",
"doc_url": "…/errors/invalid_request.md",
"fix": "the request body or parameters failed validation; see param"
}
}
See all error codes.