Error Codes

Complete reference of error codes returned by the PayForge API with resolution guidance.

Error Response Format

All errors follow a consistent JSON structure with a type, machine-readable code, human-readable message, and a link to documentation.

Error responsejson

{
  "error": {
    "type": "validation_error",
    "code": "amount_below_minimum",
    "message": "Payment amount must be at least 50 cents",
    "param": "amount_cents",
    "doc_url": "https://docs.payforge.dev/errors#amount_below_minimum"
  },
  "meta": {
    "request_id": "req_01GHI..."
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
401	Unauthorized — invalid or missing API key
403	Forbidden — insufficient permissions
404	Not Found — resource doesn't exist
409	Conflict — idempotency key reuse
422	Unprocessable Entity — validation failed
429	Too Many Requests — rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Authentication Errors

authentication_required401

No valid API key provided

Resolution: Include a valid Bearer token in the Authorization header.

invalid_api_key401

The API key provided is invalid or revoked

Resolution: Check your key in the dashboard. Revoked keys cannot be reused.

mfa_required403

MFA verification required for this action

Resolution: Complete MFA verification before retrying.

Authorization Errors

forbidden403

You do not have permission to perform this action

Resolution: Check your user role. Admin or manager access may be required.

no_merchant403

No merchant account associated with this user

Resolution: Ensure your user is linked to a merchant account.

Validation Errors

validation_error422

One or more parameters are invalid

Resolution: Check the error details for the specific field and constraint.

amount_below_minimum422

Payment amount must be at least 50 cents

Resolution: Ensure amount_cents >= 50.

invalid_currency422

The specified currency is not supported

Resolution: Use a supported currency: USD, EUR, GBP, CAD, AUD.

invalid_card_token422

The card token is invalid or expired

Resolution: Generate a new card token and retry.

Payment Errors

payment_declined422

The payment was declined by the network

Resolution: The cardholder should contact their issuing bank.

fraud_blocked422

Payment blocked by fraud detection

Resolution: Review the fraud case in the dashboard. Contact support if this is a false positive.

already_captured422

This payment has already been captured

Resolution: A payment can only be captured once.

already_voided422

This payment has already been voided

Resolution: Voided payments cannot be modified.

capture_expired422

Authorization has expired and can no longer be captured

Resolution: Create a new payment. Authorizations expire after 7 days.

Rate Limiting

rate_limit_exceeded429

Too many requests

Resolution: Back off and retry with exponential backoff. Default limit: 100 req/min.

Resource Errors

not_found404

The requested resource does not exist

Resolution: Verify the resource ID. Resources are scoped to your merchant.

idempotency_conflict409

A different request was already made with this idempotency key

Resolution: Use a unique X-Idempotency-Key for each distinct request.

Server Errors

internal_error500

An unexpected error occurred

Resolution: Retry the request. If the issue persists, contact support with the request_id.

service_unavailable503

The service is temporarily unavailable

Resolution: Retry with exponential backoff. Check status.payforge.dev for incidents.