Skip to main content
Fingo Pay uses conventional HTTP status codes and returns a consistent JSON error body on every non-2xx response. Each error includes a machine-readable 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

The error.type field tells you the broad category of the problem. Use it to decide how your integration should respond.
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, 409
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, 403
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: 429
The requested resource does not exist. This applies to transactions, accounts, shortcodes, and other resources looked up by ID or reference.Typical HTTP status: 404
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: 409
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: 500

Error codes

The error.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.
401 Unauthorized
403 Forbidden
400 Bad Request
400 Bad Request
400 Bad Request
400 Bad Request
409 Conflict
409 Conflict
404 Not Found
429 Too Many Requests
The response includes a Retry-After header with the number of seconds to wait before retrying.
500 Internal Server Error

Handling errors

Use error.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.
Always log the requestId from error responses. Fingo Pay support can use it to trace the exact request in our systems.

HTTP status codes

A summary of HTTP status codes returned by the Fingo Pay API and what they mean.