Errors

Error format#

{
  "error": {
    "code": "validation_failed",
    "message": "Amount must be at least 1.",
    "fields": [{ "field": "amount_minor", "message": "Must be at least 1." }]
  },
  "request_id": "01a177b9-1822-7a41-b8d9-119d16df9ecc"
}

• code: a stable word to branch on in your code.
• message: a sentence for people. Do not parse it.
• fields: for validation errors, which fields were wrong and why.
• request_id: quote this when you contact support.

Error codes#

• 400malformed_requestThe request body could not be read.
• 400validation_failedThe request does not match the API: a required field is missing or a value has the wrong form. The message names the field.
• 401unauthenticatedThe secret key is missing, invalid or revoked.
• 403permission_deniedThe key is not allowed to do this, or the request came from an address that is not on its allowlist.
• 403business_verification_requiredYour business has to be verified before this can be done.
• 404not_foundThat record does not exist for this business and mode.
• 409conflictThe request clashes with the current state, such as a reference reused with different details.
• 409idempotency_key_reusedThat idempotency key was already used with a different request.
• 409provider_profile_requiredYour business has no active provider profile for virtual accounts in this mode, or the provider connection its profile uses is not enabled.
• 409settlement_destination_unconfirmedUnder a FastPay-managed profile, live accounts are not available on that provider yet, or the profile has not been confirmed to pay your own settlement account.
• 409virtual_account_existsThe customer already has an open static account with that provider.
• 413payload_too_largeThe request body is too large.
• 422validation_failedThe request is well formed but cannot be served as sent, such as a field the chosen provider needs. The fields list says which, when a field is the cause.
• 429rate_limitedToo many requests. Wait for the time in the Retry-After header.
• 500internal_errorSomething went wrong on our side. Retry, and quote the request_id if it keeps happening.
• 502provider_unavailableThe provider returned an account FastPay cannot use. No account was opened, and the one started is marked failed: retry with the same idempotency key.
• 503service_unavailableFastPay is briefly unable to answer. Retry shortly.
• 503provider_unavailableThat provider cannot open virtual accounts right now, or could not be asked to. No account was opened, and any account started is marked failed: retry later with the same idempotency key.

Which errors to retry#

Retry 429, 500, 502 and 503, waiting longer each time. Do not retry other 4xx errors: the request itself has to change. When you retry a request that creates something, send the same idempotency key or reference.