Errors

NextAPI uses standard HTTP status codes combined with structured error responses that include machine-readable error codes and human-readable messages.

Error response format

All errors return JSON with a consistent structure:

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "The account does not have enough available balance to complete this request.",
    "details": {
      "available_balance": 5000,
      "requested_amount": 10000
    }
  }
}

Field	Description
error.code	Machine-readable error identifier — use this in your error handling logic
error.message	Human-readable description — suitable for logging, not for showing end users
error.details	Optional additional context — varies by error type

HTTP status codes

Status	Meaning	When it occurs
200 OK	Success	Request completed successfully
201 Created	Resource created	POST request created a new resource
400 Bad Request	Invalid request	Missing required fields, wrong data types, or malformed JSON
401 Unauthorized	Authentication failed	Invalid or missing Authorization header
403 Forbidden	Access denied	Valid credentials but insufficient permissions
404 Not Found	Resource not found	The requested ID does not exist or is not accessible to your account
409 Conflict	Duplicate request	Idempotency key reuse with different parameters
422 Unprocessable Entity	Business rule violation	Request is valid but cannot be processed (e.g., insufficient funds)
429 Too Many Requests	Rate limited	Too many requests in a short period
500 Internal Server Error	Server error	Unexpected server-side failure — retry with backoff

Domain error codes

Funds and balances

Code	Status	Description	Resolution
INSUFFICIENT_FUNDS	422	Account available balance is too low	Check balance via GET /v2/accounts/{id}/balances before requesting payout
ACCOUNT_FROZEN	422	Account is frozen for compliance reasons	Contact NextPay support
AMOUNT_BELOW_MINIMUM	422	Amount is below the rail minimum	Increase amount or use a different rail
AMOUNT_ABOVE_MAXIMUM	422	Amount exceeds the rail maximum (e.g., InstaPay PHP 50k)	Split into multiple requests or use PESONet

Recipients and accounts

Code	Status	Description	Resolution
INVALID_ACCOUNT	422	Recipient account number is invalid or does not exist	Verify the account number with the recipient
ACCOUNT_CLOSED	422	Recipient account is closed	Use a different account for this recipient
INVALID_INSTITUTION	400	Bank or e-wallet code is not recognized	Check valid codes via GET /v2/receiving-institutions

Payment rails

Code	Status	Description	Resolution
BANK_UNAVAILABLE	422	The target bank is temporarily unavailable	Retry later; check GET /v2/service-health
RAIL_UNAVAILABLE	422	InstaPay or PESONet is down	Retry later or wait for scheduled batch window
PROCESSING_FAILED	422	Payout was rejected by the payment network	See payout details for provider-specific reason

Authentication and authorization

Code	Status	Description	Resolution
INVALID_CREDENTIALS	401	Client ID or Client Secret is incorrect	Verify credentials in your dashboard
UNAUTHORIZED	401	Authorization header missing or malformed	Include Authorization: Basic <base64> in every request
FORBIDDEN	403	Credentials valid but access denied	Verify your account has the required permissions

Requests

Code	Status	Description	Resolution
VALIDATION_ERROR	400	Request body failed validation	Read error.details for the specific field and constraint
RESOURCE_NOT_FOUND	404	Requested ID does not exist	Verify the ID is correct and belongs to your account
IDEMPOTENCY_CONFLICT	409	Same idempotency key used with different parameters	Use a new key or replay the exact same request
RATE_LIMITED	429	Too many requests	Back off and retry after the Retry-After header value

Related

• Handle Errors and Retries — classification logic, exponential backoff, crash recovery, and alerting patterns
• IDs & Idempotency — prevent duplicate transactions with X-Idempotency-Key
• Handle Payout Failures — payout-specific failure recovery
• Disbursement Channels — understand rail limits and routing