Skip to main content
Every code Ringup returns. The doc_url on a live error links straight to its entry here. For the envelope these arrive in, see Errors.

​
invalid_request_error

The request is malformed, or names something that does not exist. Fix the request; retrying it unchanged will fail the same way.
No saved card with that id belongs to this caller.Resolution. Use an instrument_id returned by identify.Your agent says. “That card could not be processed. Would you like to try a different card?”Then. offer_different_card
The credentials object is missing or not a plain object.Resolution. Send credentials as a JSON object matching the processor’s shape.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
environment must be test or live.Resolution. Send one of the two supported values.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
events contains an unsupported event type.Resolution. Subscribe only to documented event types, or omit to receive all.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The request body is not valid JSON.Resolution. Send a JSON body with Content-Type: application/json.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
payment_policy is not one of the supported values.Resolution. Use required, above_amount, or optional.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
payment_policy is above_amount but payment_policy_amount_cents is missing or not a positive integer.Resolution. Send a positive integer threshold with the above_amount policy.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
processor is not one of the supported processors.Resolution. Use a supported processor value.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The state key is missing or outside the allowed namespace.Resolution. Use a key within the documented namespace.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The requested lifetime is outside the allowed range.Resolution. Send a ttl within the documented bounds.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The webhook URL is missing or not a valid https URL.Resolution. Send an absolute https URL.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
A parameter was present but its value is not acceptable.Resolution. The param attribute names the offending field.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
vault is not one of the supported vault kinds.Resolution. Use a supported vault value, or omit it.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
No API key with that id belongs to your account.Resolution. Check the key id.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The merchant exists but has not finished connecting their payment processor, so no charge can settle.Resolution. Send the merchant through the Connect button; wait for the merchant.connected webhook.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
No merchant with that id belongs to your account.Resolution. Check the merchant id, and that it was created with this account’s key.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
checkout_session_id is required for this call.Resolution. Pass the id returned by create_checkout.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The instrument payload is missing required fields.Resolution. The param attribute names the first missing field.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
A required parameter is missing.Resolution. The param attribute names the first missing field.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The caller has no card on file usable at this merchant, so there is nothing to charge. Expected for a first-time caller at a per-merchant processor.Resolution. Send a pay link so the caller can add a card.Your agent says. “I can text you a secure link to pay instead. Would that work?”Then. send_link
No route matches this path and method.Resolution. Check the method and path against the API reference.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
This processor cannot resolve an order total by reference.Resolution. Send amount_cents instead of order_id for this processor.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
That saved card cannot be charged at this merchant, because it lives in a different processor’s wallet.Resolution. Charge a card from the merchant’s own processor, or send a pay link to enroll one.Your agent says. “I can text you a secure link to pay instead. Would that work?”Then. send_link
The checkout session passed its expiry and can no longer be paid.Resolution. Create a new checkout session.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The session has no caller identity attached, so no card can be selected.Resolution. Call identify at the start of the call before creating the session.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
No checkout session with that id belongs to your account.Resolution. Check checkout_session_id.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.

​
authentication_error

The API key is missing, malformed, or revoked. Check the Authorization header.
The API key is missing, malformed, revoked, or does not match the mode of the resource.Resolution. Send Authorization: Bearer rk_test_… (or rk_live_…) and confirm the key is not revoked.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.
The key authenticated but its vendor has no provisioned account.Resolution. Complete vendor onboarding before minting keys.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.

​
permission_error

The key is valid but is not allowed to act on this resource.
That saved card does not belong to the caller on this session.Resolution. Charge only cards returned by identify for this caller.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.

​
card_error

The card was refused. The most common error you will handle, and the only one the caller can act on: carries decline_code when the issuer gave a reason, plus the sentence your agent can say.
The issuer declined the charge. decline_code carries the specific reason where the issuer gave one.Resolution. Ask for a different card. Sensitive decline reasons are deliberately not reflected in agent_message.Your agent says. “That card could not be processed. Would you like to try a different card?”Then. offer_different_card
The processor rejected the card while saving it.Resolution. Ask for a different card. processor_code carries the processor’s own reason.Your agent says. “That card could not be processed. Would you like to try a different card?”Then. offer_different_card

​
processor_error

The merchant’s payment processor could not be reached, or rejected the request for reasons unrelated to the card. Carries processor_code. Nothing to ask the caller for.
The merchant’s stored processor credentials were rejected, so nothing can settle.Resolution. The merchant must reconnect their processor.Your agent says. “I’m not able to take payment on this line right now.”
The processor could not be reached to resolve the order total.Resolution. Retry. The processor may be temporarily unavailable.Your agent says. “I’m having trouble taking payment right now. Let me get someone to help you.”Safe to retry.
The merchant’s payment processor is unreachable or returned a server error, so the outcome of this charge is UNKNOWN. It may still have settled. Not a Ringup outage.Resolution. Repeat the same charge request: it is idempotent, so it cannot charge twice. Or wait for the webhook, which carries the settled outcome once we have reconciled it.Your agent says. “I’m still confirming that payment. I’ll send you a confirmation as soon as it comes through.”Safe to retry.

​
idempotency_error

An idempotency key was reused with different parameters.
This idempotency key was already used with different charge details.Resolution. Use a new key, or resend the original parameters unchanged.Your agent says. Nothing. This is a developer error, so agent_message, display_message and agent_action are all null.

​
rate_limit_error

Too many requests. Back off and retry.
Too many requests in a short window.Resolution. Back off and retry, honouring Retry-After.Your agent says. “I’m having trouble taking payment right now. Let me get someone to help you.”Safe to retry.

​
api_error

A fault on Ringup’s side. Safe to retry.
An unexpected fault on Ringup’s side.Resolution. Retry. If it persists, contact support with the request id.Your agent says. “I’m having trouble taking payment right now. Let me get someone to help you.”Safe to retry.
A required backend dependency is not configured in this environment.Resolution. Contact support with the request id.Your agent says. “I’m having trouble taking payment right now. Let me get someone to help you.”Safe to retry.
The checkout session could not be written.Resolution. Retry. If it persists, contact support with the request id.Your agent says. “I’m having trouble taking payment right now. Let me get someone to help you.”Safe to retry.

​
Decline codes

On a decline, decline_code carries the reason in Ringup’s own vocabulary, identical no matter which processor the merchant runs. processor_code carries that processor’s raw value, unmodified, for tracing a specific decline back to its source.
Reasons your agent will never state. A card reported lost or stolen, or one flagged for fraud, returns exactly the same sentence as an ordinary decline, so your agent cannot reveal it and a person listening cannot infer it. The real reason still reaches you in decline_code and processor_code.
This is an allowlist, not a blocklist: only the reasons in the table above are ever stated plainly. Every other reason, whether sensitive or simply one we have not catalogued, falls back to “That card could not be processed. Would you like to try a different card?” Processors add and rename decline codes without notice, so a new or undocumented reason is safe by default rather than safe only until someone updates a list.

​
Advice codes

Every error carries advice_code, our guidance on what to do programmatically. It is separate from agent_action, which drives the conversation: a card can be “do not retry this card” while the agent still offers a different one.

​
Next steps

Handling errors

What to catch, and what your agent says out loud.

Errors

The envelope and its attributes.