Errors

Error response format

All errors follow a consistent envelope:

{
  "error": {
    "code": "invalid_amount",
    "message": "Amount must be a positive integer"
  }
}

HTTP status codes

Status	Meaning
`400 Bad Request`	Invalid or missing parameters
`401 Unauthorized`	Missing, invalid, or revoked API key
`403 Forbidden`	Live mode not activated, or unauthorized access
`404 Not Found`	Resource not found or belongs to another merchant
`409 Conflict`	Idempotency key in-flight (retry in a moment)
`422 Unprocessable Content`	Business rule violation (invalid state transition, over-refund, etc.)
`429 Too Many Requests`	Rate limit exceeded — check `Retry-After` header
`500 Internal Server Error`	Unexpected server error
`503 Service Unavailable`	Provider is unreachable

Error codes

Auth errors

Code	Status	Description
`unauthorized`	401	Missing or invalid Bearer token
`invalid_credentials`	401	Wrong email or password
`token_expired`	401	JWT has expired — log in again
`token_revoked`	401	JWT was invalidated by logout
`api_key_revoked`	401	API key has been revoked
`live_mode_disabled`	403	Live keys not activated in this instance

Charge errors

Code	Status	Description
`invalid_amount`	400	Amount is not a positive integer
`unsupported_currency`	400	Currency not in the supported list
`unsupported_payment_method`	400	Payment method not enabled for your account
`idempotency_key_required`	400	`Idempotency-Key` header is missing
`idempotency_conflict`	409	Same key used with different parameters
`invalid_state_transition`	422	Charge cannot move to the requested state
`provider_declined`	422	Card declined by the payment provider
`charge_not_found`	404	Charge ID doesn't exist or belongs to another merchant

Refund errors

Code	Status	Description
`refund_exceeds_charge`	422	Refund amount would exceed original charge
`charge_not_capturable`	422	Can only refund `captured` charges
`charge_not_voidable`	422	Can only void `authorized` charges

Handling errors

const response = await fetch("https://paygate-api.fly.dev/v1/charges", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${secretKey}`,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ charge: chargeData }),
});

if (!response.ok) {
  const { error } = await response.json();
  console.error(`[${error.code}] ${error.message}`);
  // Handle specific codes
  if (error.code === "provider_declined") {
    // Ask user to try a different card
  }
}

Provider errors

When the underlying payment provider declines a charge, Paygate surfaces it as provider_declined (422). The charge record is saved with status failed so you have an audit trail.

On this page