Errors

One envelope, every endpoint. The same object comes back from every call, so you write one parser. A declined charge is no exception: it arrives as a 402 in this same shape. Branch on type first, then refine on code.

{
  "error": {
    "type": "processor_error",
    "code": "card_declined",
    "audience": "caller",
    "decline_code": "insufficient_funds",
    "advice_code": "try_again_later",
    "message": "Charge declined by the issuer.",
    "agent_message": "That card was declined for insufficient funds. Would you like to try a different card?",
    "display_message": "That card was declined for insufficient funds.",
    "agent_action": "offer_different_card",
    "doc_url": "https://docs.ringup.dev/api-reference/error-codes#card_declined",
    "charge": "chg_77386e2f",
    "request_id": "req_8f3c1d2ab4e9"
  }
}

Attributes

string

The broad class. Branch on this first: it is a small, stable set, listed below.

string

The specific, machine-readable reason. Every code is catalogued in Error codes.

string

Who this error is for: developer or caller. It decides whether the three spoken fields carry anything. See Handling errors.

string

A developer-facing explanation. Written for your logs. Never speak this to a caller.

string | null

The sentence your voice agent can say, verbatim. Null on every developer error.

string | null

The same fact written to be read rather than spoken, for a screen or an SMS. Null on every developer error.

string | null

The next payment move, when there is one: retry_card, offer_different_card, or send_link. Null whenever the next move is not ours to choose.

string

Our guidance on retrying: try_again_later, confirm_card_data, or do_not_try_again. Present on every error.

string

The charge this error relates to, when there is one.

string

The parameter at fault, when one field caused the error.

string

The issuer’s reason, on a decline. For your logs. Sensitive reasons are deliberately not reflected in agent_message.

string

The processor’s own code, unmodified, on a processor_error.

string

Links straight to that code’s entry in Error codes.

string

Unique per request, also returned as the Ringup-Request-Id header on every response. Quote it in support requests: it matches our logs exactly.

Error types

Branch on type first. It is seven values and it changes rarely; code refines within it.

error type

The request is malformed, or names something that does not exist. Fix the request; retrying it unchanged will fail the same way.

error type

The API key is missing, malformed, or revoked. Check the Authorization header.

error type

The key is valid but is not allowed to act on this resource.

error type

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.

error type

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.

error type

An idempotency key was reused with different parameters.

error type

Too many requests. Back off and retry.

error type

A fault on Ringup’s side. Safe to retry.

Every endpoint in this reference lists the specific codes it can return, so you never have to hold the whole catalog in mind to know what one call can do.

API reference

Tools

Events

Errors

Attributes

Error types

Next steps

Error codes

Handling errors

​Attributes

​Error types

​Next steps

Error codes

Handling errors

Attributes

Error types

Next steps