Errors

Nexpay uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Nexpay’s servers.

HTTP status code summary

Maintenance mode

In rare cases, Nexpay may enter maintenance mode for scheduled infrastructure work. When this happens, the API responds with HTTP status code 503 Service Unavailable and includes a Retry-After header indicating the estimated time (in seconds) until the maintenance window ends. These windows are communicated in advance and you can monitor real-time status at status.nexpay.com.

During maintenance:

• New payment attempts will fail.
• Dashboard login will be unavailable.
• Background operations (notifications, bank-related events) are queued and processed automatically once maintenance is over.
• Health checks, webhook subscriptions, and payment gateway callbacks continue to operate normally.

Error codes

In addition to HTTP status codes, Nexpay returns application-level error codes to help you identify the specific issue. Each error code follows the format [PREFIX####], where:

• PREFIX is a 3-letter module identifier (e.g., PAY for Payments, AUT for Authentication)
• #### is a zero-padded numeric code unique within that module

For example, [PAY0001] means "Payment not found" and [QOT0001] means "Quote has expired". These codes remain stable and can be used to programmatically handle specific error scenarios, even if the human-readable message changes over time.

Module prefixes

Error code reference

Error response

Error responses include the HTTP status code, the error code, a human-readable message, a timestamp, and optionally details with additional context:

{
  "statusCode": 404,
  "code": "[PAY0001]",
  "message": "[PAY0001] Payment not found",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Some errors may include a details field with additional context about the issue:

{
  "statusCode": 422,
  "code": "[QOT0003]",
  "message": "[QOT0003] Currency pair unavailable",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "details": {
    "fromCurrency": "BRL",
    "toCurrency": "USD"
  }
}

If the request failed due to the lack of permissions, Nexpay will return a 403 Forbidden error:

{
  "statusCode": 403,
  "code": "[GEN9004]",
  "message": "[GEN9004] Forbidden",
  "timestamp": "2026-01-15T10:30:00.000Z"
}