Errors | Alphabet Bridge Docs

Every error from /api/v1 has the same shape: an error object with a machine-readable code and a human-readable message. Some codes add fields, listed below. Branch on code, never on message, which can change.

json

{
  "error": {
    "code": "validation_failed",
    "message": "The amount field must be at least 250. (and 1 more error)",
    "fields": {
      "amount": ["The amount field must be at least 250."],
      "order_reference": ["The order reference field is required."]
    }
  }
}

Every error code

HTTP	`code`	What happened	What to do
401	`unauthenticated`	No `Authorization: Bearer …` header.	Send your API key. See Authentication.
401	`invalid_api_key`	The key is unknown, revoked or was rolled.	Use the current key from the dashboard.
403	`application_disabled`	The application is switched off.	Contact Alphabet. Retrying will not help.
403	`application_pending_review`	Alphabet has not activated the application yet.	Wait for activation.
403	`application_suspended`	Alphabet has suspended the application.	Contact Alphabet. Retrying will not help.
403	`ip_not_allowed`	The request came from an IP address outside your application's allow-list.	Call from an allowed server, or ask Alphabet to add the address.
404	`not_found`	No payment with this id for this application in this mode, or an unknown path.	Check the id, and that you used a key of the same mode (test or live).
409	`order_reference_already_paid`	This `order_reference` already has a `pending`, `paid` or refunded payment. Adds `payment_id`.	Use that payment: send the customer to its `checkout_url`, or treat the order as paid.
409	`idempotency_key_reused`	The `Idempotency-Key` was used before with a different body.	Use a new key for a different request.
409	`idempotency_request_in_progress`	The first request with this `Idempotency-Key` is still running.	Retry after a moment.
409	`payment_not_cancellable`	Cancel was asked for a payment that is no longer `pending`. Adds `status`.	If it is `paid`, deliver or refund; a paid payment is never cancelled.
409	`payment_not_refundable`	Refund was asked for a payment that is not `paid` or `partially_refunded`. Adds `status`.	Fetch the payment to see its status.
409	`payment_busy`	The payment is being updated at that moment.	Retry after a few seconds.
422	`validation_failed`	One or more fields are invalid. Adds `fields`: each field with its messages.	Fix the listed fields. The same body gives the same answer.
422	`method_required`	Your application offers several payment methods and `method` was not sent.	Send `method`.
422	`method_not_enabled`	The `method` is not enabled for your application, or none is.	Contact Alphabet.
422	`amount_below_minimum`	`amount` is below your application's minimum. Adds `min_amount`.	Raise the amount.
422	`amount_above_maximum`	`amount` is above your application's maximum. Adds `max_amount`.	Split the order or ask Alphabet to review the limit.
422	`return_url_not_allowed`	A `return_url` was sent whose host differs from your application's own return-URL host.	Omit `return_url` or send one on the same host. See Payments.
422	`refund_amount_exceeds_refundable`	The refund is more than what is left. Adds `refundable_amount`.	Refund at most `refundable_amount`.
422	`refunds_processed_manually`	A live key asked for a refund. Adds `docs_url`.	Request the refund from the dashboard. See Refunds.
429	`rate_limited`	More than 120 requests a minute with this key.	Wait the seconds in the `Retry-After` header, then retry.
502	`provider_error`	The payment provider refused or did not answer. On create, adds `payment_id`: that payment is now `failed`.	Retry later. On create, retry with a new payment; the same `order_reference` is free again.
500	`server_error`	Something failed on the bridge's side.	Retry with backoff. On create, retry with the same `Idempotency-Key`.
other	`http_error`	Any other HTTP error, for example `405` for a wrong method on a path.	Check the method and path.

Retrying safely

4xx errors other than 409 idempotency_request_in_progress, 409 payment_busy and 429 will give the same answer again until you change the request.
5xx errors and network failures can be retried. Send an Idempotency-Key on POST /api/v1/payments so a retry never creates a second payment. See Payments.