invalid_request

The request body or query parameters failed validation. Nothing was changed.

HTTP 400

When you see this

Canopy validates every /api/v1/* request before it changes anything. It returns invalid_request when that check fails. Two examples:

A POST /api/v1/intents body is missing a required field, or has a field of the wrong type.
A GET /api/v1/intents request has a cursor query parameter that is not a non-negative integer.

Two other errors are also 400s, with a different code. invalid_json means the body is not valid JSON. unsupported_version means the Canopy-Version header names a version Canopy does not serve.

What the response looks like

Every /api/v1/* error has this shape, with keys in this order. param and detail are left out when they do not apply. They are never sent as null.

json

{
  "error": {
    "code": "invalid_request",
    "message": "The request body failed validation.",
    "param": "priceUnits",
    "request_id": "req_1a2b3c4d5e6f7a8b9c0d1e2f",
    "docs": "https://canopypay.io/errors/invalid_request"
  }
}

param names the first field that failed, in dot-path notation (metadata.reference for a nested field). Validation stops at the first problem. Other fields may also be wrong.

What to do

Check the request against the operation's documented schema. Start with the field named in param. Fix this on your side. Retrying the same request fails the same way, so Canopy's SDK never retries invalid_request.

If the request looks correct and you still get invalid_request, contact support. Include the request_id from the error body. It identifies this exact request in Canopy's logs.