Error codes and messages - Bridge by LINK

Use the code field to decide what to do. Messages are shown as examples; IDs and amounts in them change.

Request and setup

Code	Status	Example message	How to fix
`bad_request`	400	The request could not be understood.	Check your JSON is valid.
`api_version_required`	400	The API-Version header is required and must be the version set on this account.	Add the `API-Version` header.
`invalid_api_version`	400	’2026-9-22’ is not a valid API version. Expected YYYY-MM-DD-name, for example 2026-10-29-atlas.	Fix the spelling.
`api_version_mismatch`	400	The API-Version ’…’ does not match the version set on this account (’…’).	Send the version shown in the Bridge app (Settings → Account).
`unsupported_api_version`	400	The requested API version ’…’ is not supported.	Use a supported version.
`api_version_sunset`	400	API version ’…’ is no longer supported. Migrate to ’…’.	Move to the newer version.
`payload_too_large`	413	The request body is too large.	Keep the body under 10 KB.
`route_not_found`	404	The requested route does not exist.	Check the URL and method.
`rate_limit_exceeded`	429	Too many requests	Wait for `Retry-After`.

Access

Code	Status	Example message	How to fix
`authentication_failed`	401	Missing X-BRIDGE-API-Key header.	Send your API key. See all key messages.
`forbidden`	403	This IP address is not allowed to call the API. This request came from 198.51.100.7. …	Add the address to your IP allowlist.
`forbidden`	403	This API key does not have access to this resource.	Give the key the right scope.
`forbidden`	403	This organization does not have access to this service.	Contact support.
`pair_not_enabled`	403	The USDC/NGN pair is not enabled for this business. Contact support to enable it before creating onramp transactions.	Turn the pair on in Currency pairs.

Fields

Code	Status	Example message	How to fix
`validation_failed`	422	Request validation failed	Read the `errors` list. Each entry names the `field` and the problem.
`invalid_amount`	422	Invalid amount 1000 NGN: minimum is 15000	Stay within the limits.

Customers

Code	Status	Example message	How to fix
`customer_not_found`	404	Customer cus_… not found	Check the ID. It must belong to your business and environment.
`customer_banned`	409	Customer cus_… is banned	Contact support.

Quotes

Code	Status	Example message	How to fix
`quote_not_found`	404	Quote qte_… not found	Get a new quote. Unused quotes are deleted 10 minutes after they expire.
`quote_expired`	400	Quote qte_… has expired	Refresh the quote.
`quote_locked`	409	Quote qte_… is locked and cannot be refreshed	The quote is already used by a payment. Get a new quote for a new payment.

Payments

Code	Status	Example message	How to fix
`payment_not_found`	404	Payment pay_… not found	Check the ID.
`payment_already_completed`	409	Payment pay_… is already completed	Nothing to do.
`payment_canceled`	400	Payment pay_… has been canceled	Create a new payment.
`invalid_transition`	400	Invalid status transition on payment pay_…	The payment can’t move to that step from where it is.
`payment_processing_failed`	422	Failed to process payment pay_…: …	Read the reason. Try again with a new quote.
`risk_review_required`	422	Risk review required	The payment needs a manual check. Contact support.
`transaction_blocked`	422	Transaction blocked: …	The payment was blocked by our risk checks. Contact support.

Retries

Code	Status	Example message	How to fix
`idempotency_conflict`	409	A request with this Idempotency-Key is already being processed.	Wait, then retry.
`idempotency_conflict`	409	This Idempotency-Key was used with a different request payload.	Use a new key for a different request.

Our side

Code	Status	Example message	How to fix
`route_temporarily_unavailable`	503	This route temporarily unavailable	Retry later.
`request_timeout`	504	Request timed out	Retry with the same `Idempotency-Key`.
`database_error`	503	(varies)	Retry later.
`unexpected_error`	500	An unexpected error occurred.	Retry later. Contact support with the `request_id` if it continues.

Last modified on October 29, 2026