type and code you can use for programmatic handling, a human-readable message for debugging, and a requestId you can reference when contacting support.
Error body
Every error response follows this structure:string
required
The category of error. Use this to determine the general class of the problem. See Error types below.
string
required
A specific, machine-readable error code for programmatic handling. See Error codes below.
string
required
A human-readable description of the error. Intended for developer logs and debugging — do not display raw error messages to end users.
string | null
The request parameter that caused the error, when applicable. Useful for highlighting the specific field in your UI or logs. Returns
null when the error is not tied to a single parameter.string
A unique identifier for the request. Always include this when contacting Fingo Pay support.
Error types
Theerror.type field tells you the broad category of the problem. Use it to decide how your integration should respond.
invalid_request_error
invalid_request_error
The request was malformed or contained invalid data. This covers missing parameters, bad values, schema validation failures, and missing headers. Check
error.code and error.param for specifics.Typical HTTP status: 400, 409authentication_error
authentication_error
The request could not be authenticated. The API key is missing, invalid, expired, or the authenticated organization does not have permission to perform the action.Typical HTTP status:
401, 403rate_limit_error
rate_limit_error
Your organization has exceeded the allowed request rate. Back off, respect the
Retry-After header, and retry. See Rate limits for details.Typical HTTP status: 429not_found_error
not_found_error
The requested resource does not exist. This applies to transactions, accounts, shortcodes, and other resources looked up by ID or reference.Typical HTTP status:
404conflict_error
conflict_error
The request conflicts with the current state of a resource. Most commonly returned when an idempotency key is reused with a different request body, path, or method.Typical HTTP status:
409api_error
api_error
An unexpected error occurred on the Fingo Pay server. These are rare. If you encounter one, retry with exponential backoff and contact support if it persists.Typical HTTP status:
500Error codes
Theerror.code field provides a specific, machine-readable identifier for the error. Use it for programmatic branching in your integration.
Sample error responses
Realistic response bodies for the most common error scenarios.403 — Forbidden (organization not verified)
403 — Forbidden (organization not verified)
403 Forbidden
400 — Missing parameter
400 — Missing parameter
400 Bad Request
400 — Invalid parameter
400 — Invalid parameter
400 Bad Request
400 — Validation error
400 — Validation error
400 Bad Request
400 — Missing header (Idempotency-Key)
400 — Missing header (Idempotency-Key)
400 Bad Request
409 — Idempotency conflict
409 — Idempotency conflict
409 Conflict
409 — Duplicate merchantTransactionId
409 — Duplicate merchantTransactionId
409 Conflict
404 — Resource not found
404 — Resource not found
404 Not Found
429 — Rate limit exceeded
429 — Rate limit exceeded
429 Too Many Requests
The response includes a
Retry-After header with the number of seconds to wait before retrying.500 — Internal server error
500 — Internal server error
500 Internal Server Error
Handling errors
Useerror.type to categorize the problem, error.code to decide what your application should do, error.param to surface which field failed, and error.message for developer-facing logs.