API reference

Errors

TigerPay uses normal HTTP status codes. When a request fails, the body is always the same JSON shape.

The error format#

{
  "error": {
    "type": "invalid_request",
    "code": "parameter_invalid",
    "message": "amount: must be a decimal string with two decimals, such as \"340.00\""
  }
}

Field	Details
`type`	The kind of error. One of the types below. Use it for broad handling.
`code`	A short, stable name for the exact problem. Use it in your code.
`message`	A sentence for humans. It can change, so do not match on it. Do not show it to your customers.

TigerPay never sends stack traces, database errors, or messages from the payment provider in an error.

Error types#

Type	HTTP status	Meaning	What to do
`invalid_request`	400, 404, 409	Your request is wrong or does not fit the current state.	Fix the request. Do not retry it unchanged.
`authentication`	401, 403	The API key is missing, wrong, or not allowed.	Check the key and its mode.
`rate_limit`	429	Too many requests.	Wait for `Retry-After` seconds. See Rate limits.
`payment_provider`	502	The payment provider rejected the request or could not be reached.	`provider_unavailable` is temporary: retry. See the notes on refunds.
`api_error`	500	Something went wrong on our side.	Retry after a short wait. If it keeps happening, contact TigerPay.

Error codes#

Code	Meaning
Requests
`invalid_json` HTTP 400	The body is not valid JSON, or is not a JSON object.
`parameter_invalid` HTTP 400	A field is missing, has the wrong type, or breaks a rule. The message starts with the field name.
`invalid_request` HTTP 400	The request has fields TigerPay does not know. The message lists them.
`route_not_found` HTTP 404	That URL and method do not exist.
`resource_missing` HTTP 404	No payment or refund with that id for your account and mode. A test key cannot see live data and the other way round.
Payments and refunds
`payment_not_cancellable` HTTP 400	Only a `pending` payment can be cancelled.
`payment_not_refundable` HTTP 400	Only a `succeeded` payment can be refunded.
`refund_window_expired` HTTP 400	The payment succeeded more than 180 days ago, so it can no longer be refunded. See refunds.
`payment_fully_refunded` HTTP 400	Nothing is left to refund on this payment.
`refund_exceeds_remaining` HTTP 400	The refund is more than what is left to refund.
Idempotency
`idempotency_key_invalid` HTTP 400	The `Idempotency-Key` header is not 1 to 255 printable characters.
`idempotency_key_reused` HTTP 409	This key was already used for a different request.
`idempotency_conflict` HTTP 409	A request with this key is still running. Try again shortly.
Authentication
`missing_api_key` HTTP 401	No `Authorization: Bearer` header.
`invalid_api_key` HTTP 401	The key is wrong, badly formed or revoked.
`live_mode_not_enabled` HTTP 403	Live payments are not enabled for your account yet.
`account_inactive` HTTP 403	The merchant account is not active.
Limits
`rate_limit_exceeded` HTTP 429	More than 100 requests in a minute for this key.
Payment provider
`provider_rejected` HTTP 502	The payment could not be created.
`refund_rejected` HTTP 502	The refund was declined. It is saved as `failed`.
`provider_unavailable` HTTP 502	A temporary problem reaching the payment provider.
Our side
`internal_error` HTTP 500	An unexpected error on our side.
`configuration_error` HTTP 500	Payments are not set up correctly for this account. Contact TigerPay.

New codes may be added over time. Always keep a default branch for codes you do not know, and use type and the HTTP status for it.

Handling errors#

const res = await fetch("https://api.tigerpay.app/v1/payments", { /* … */ });
const data = await res.json();

if (!res.ok) {
  const { type, code, message } = data.error;
  console.error("TigerPay error", res.status, type, code, message);

  if (res.status === 429) {
    // wait for the Retry-After header, then try again
  } else if (res.status >= 500) {
    // temporary: retry with the same Idempotency-Key
  } else {
    // our fault or yours to fix: do not retry unchanged
  }
}

TigerPay API documentation, version 1. Base URL: https://api.tigerpay.app/v1