Developer platform

Errors

ForgePay API errors use a consistent JSON shape with a request id for support and logging.

ForgePay is not a bank. ForgeCredit is an internal settlement unit for services available in the ForgePay ecosystem.

Error format

Every API error contains `code`, `message`, optional `details` and `request_id`.

JSONjson

{
  "code": "validation_error",
  "message": "Checkout session request is invalid.",
  "details": [
    {
      "path": "amount_fgc",
      "message": "Amount must be positive."
    }
  ],
  "request_id": "req_123"
}

Common error codes

Handle these errors explicitly and log `request_id` for troubleshooting.

`unauthorized` - API key is missing or invalid.
`validation_error` - request fields are missing or malformed.
`rate_limited` - too many requests in the current window.
`idempotency_key_required` - POST request needs an idempotency key.
`idempotency_key_conflict` - same key was reused with a different body.
`checkout_session_not_found` - the checkout session does not belong to the merchant.