Errors | API Docs

Errors use standard HTTP status codes. An error response never includes data, so you can’t read partial results from a failed request.

Error shape

json · 422 Unprocessable Content

{
    "code": "4220000",
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
        "amount": [
            "The amount field must be greater than 0."
        ],
        "success_url": [
            "The success url field must be a valid URL."
        ]
    }
}

Fields

Field	Type	Description
`code`	`string`	A 7-digit code for the exact case, listed below. Branch on this, not on `message`.
`success`	`boolean`	Always `false` on an error.
`message`	`string`	What went wrong, for people. It can change; don’t parse it.
`errors`	`object`	Only on `422`: each field that failed, with its messages.

json · 409 Conflict

{
    "code": "4090001",
    "success": false,
    "message": "This Idempotency-Key was already used with a different request."
}

Status codes

Status	Meaning
`200`	Read or action succeeded.
`201`	A resource was created.
`202`	Accepted: queued to run shortly, such as a webhook repost.
`400`	The request body could not be read.
`401`	Missing or invalid API key.
`403`	The key can’t make this request, for example from an address outside its allowlist.
`404`	The resource doesn’t exist, or it belongs to another merchant or mode.
`405`	This method isn’t allowed on this path.
`409`	Conflict, such as an `external_reference_id` or Idempotency-Key reused with a different request, or canceling a payment that is no longer pending.
`422`	Validation failed. A number sent as a string also fails here.
`429`	Too many requests. Wait, then retry.
`500`	Something went wrong on our side. Retry the same request.
`501`	That channel isn’t live through the API yet.

Error codes

code	HTTP	When	What to do
`4000000`	400	The request body isn’t valid JSON.	Send a valid JSON body with `Content-Type: application/json`.
`4010000`	401	The API key is missing, malformed, deleted or regenerated.	Send a current key as `Authorization: Bearer wv_...`.
`4030000`	403	This key can’t make this request, for example from an address outside its IP allowlist.	Call from an allowed address, or update the key’s allowlist in the dashboard.
`4030001`	403	A live key was sent from a browser page. Live keys belong on your server.	Use a test key in the browser (Try It takes test keys only), and call Weav with live keys only from your server.
`4040000`	404	Not found in this mode for your account.	Check the reference and that you use a live or test key to match.
`4050000`	405	This method isn’t allowed on this path.	Check the method in the endpoint’s docs.
`4090001`	409	The `external_reference_id` (or Idempotency-Key) was already used with a different request.	Use a new reference for a new payment; never change a request and keep its reference.
`4090002`	409	The same request is still in progress.	Wait a moment, then retry it.
`4090101`	409	The payment can’t be canceled: it’s no longer pending.	Retrieve the payment for its final status.
`4090102`	409	The payment can’t be canceled at the provider right now.	Retry shortly. The payment stays pending until then.
`4090201`	409	The webhook is still being sent.	Repost it once the current delivery finishes.
`4090301`	409	The checkout can’t be canceled: it’s no longer open.	Retrieve the checkout for its status.
`4090302`	409	The checkout’s payment in progress can’t be canceled at the provider right now.	Retry shortly. The checkout stays open until then.
`4090401`	409	The saved card can’t be removed at the card processor right now.	Retry shortly. It stays chargeable until then.
`4220000`	422	Validation failed. `errors` lists each field, for example an amount outside your payment limits, a reused `external_reference_id` or a private webhook URL.	Fix the fields named in `errors` and send again.
`4220101`	422	The channel is off for your account.	Turn it on under Channels in the dashboard, or contact support.
`4220102`	422	The channel doesn’t accept that currency.	Use a currency listed in `errors.currency`.
`4220103`	422	This payment method can’t be charged.	Charge only an `ACTIVE` one. Ask your customer to save their card again if it failed or was removed.
`4220401`	422	Saving cards is off for your account.	Contact support. Weav turns it on once it has your PCI DSS evidence.
`4290000`	429	Too many requests for your account.	Wait for `Retry-After` seconds, then retry. See Rate limiting.
`4290201`	429	This payment’s webhook was reposted less than 30 seconds ago.	Wait for `Retry-After` seconds. To check the payment’s status, retrieve the payment instead.
`4290202`	429	Your account reposted 20 webhooks in this mode in the last minute.	Wait for `Retry-After` seconds. Weav already retries every webhook for about 7 days, so there’s no need to repost in bulk.
`5000000`	500	Something went wrong on our side.	Retry the same request. If it keeps happening, contact support.
`5010100`	501	That channel isn’t live through the API yet.	Use a test key for now, or contact support.

A code’s meaning never changes once published. New codes may be added, so treat an unknown one by its HTTP status.