Error Codes

Complete reference for all QPay V2 API error codes, HTTP status codes, and SDK error handling patterns. Use this page to diagnose issues and implement robust error handling in your application.

Error Response Format

When the QPay V2 API returns an error, the response body contains a JSON object with two fields:

{
  "error_code": "INVOICE_NOTFOUND",
  "message": "Invoice not found"
}

The HTTP status code is included in the response headers. Every SDK parses this into a structured error type that exposes:

HTTP Status Codes

QPay V2 uses standard HTTP status codes to indicate the result of an API request.

SDK Error Handling

Every SDK provides a structured error type and named constants for all QPay error codes. Here is how to handle errors in each language:

Go

import qpay "github.com/qpay-sdk/qpay-go"
 
invoice, err := client.CreateSimpleInvoice(ctx, req)
if err != nil {
	if qErr, ok := qpay.IsQPayError(err); ok {
		fmt.Printf("Status: %d\n", qErr.StatusCode)
		fmt.Printf("Code:   %s\n", qErr.Code)
		fmt.Printf("Message: %s\n", qErr.Message)
 
		switch qErr.Code {
		case qpay.ErrAuthenticationFailed:
			// Handle authentication failure
		case qpay.ErrInvoiceCodeInvalid:
			// Handle invalid invoice code
		case qpay.ErrInvalidAmount:
			// Handle invalid amount
		default:
			// Handle other errors
		}
	} else {
		// Network error, timeout, etc.
		fmt.Printf("Error: %v\n", err)
	}
}

JavaScript / TypeScript

import { QPayError, isQPayError, ERR_INVOICE_NOT_FOUND } from 'qpay-js';
 
try {
  await client.createSimpleInvoice(request);
} catch (err) {
  if (isQPayError(err)) {
    console.log(err.statusCode); // 404
    console.log(err.code);       // "INVOICE_NOTFOUND"
    console.log(err.message);    // Human-readable message
    console.log(err.rawBody);    // Raw response for debugging
 
    if (err.code === ERR_INVOICE_NOT_FOUND) {
      // Handle specific error
    }
  }
}

Python

from qpay import QPayError, ERR_INVOICE_NOT_FOUND
 
try:
    client.create_simple_invoice(request)
except QPayError as e:
    print(f"Status: {e.status_code}")   # 404
    print(f"Code:   {e.code}")          # "INVOICE_NOTFOUND"
    print(f"Message: {e.message}")      # Human-readable message
    print(f"Raw:    {e.raw_body}")      # Raw response
 
    if e.code == ERR_INVOICE_NOT_FOUND:
        # Handle specific error
        pass

PHP

use QPay\Exceptions\QPayException;
 
try {
    $client->createSimpleInvoice($request);
} catch (QPayException $e) {
    echo $e->statusCode;     // 404
    echo $e->errorCode;      // "INVOICE_NOTFOUND"
    echo $e->errorMessage;   // Human-readable message
    echo $e->rawBody;        // Raw response
 
    match ($e->errorCode) {
        QPayException::INVOICE_NOTFOUND => handleNotFound(),
        QPayException::AUTHENTICATION_FAILED => handleAuthError(),
        default => handleUnknown($e),
    };
}

Authentication Errors

These errors occur during token acquisition (POST /v2/auth/token) or when using an expired/invalid token.

[!NOTE] All SDKs handle token management automatically. If you receive AUTHENTICATION_FAILED, the issue is with your merchant credentials, not your code.

Invoice Errors

These errors relate to creating, retrieving, or cancelling invoices.

Payment Errors

These errors relate to checking, cancelling, or refunding payments.

Amount Errors

These errors are returned when the invoice amount is invalid.

Merchant Errors

These errors relate to merchant account status and registration.

Ebarimt (Tax Receipt) Errors

These errors relate to creating or cancelling electronic tax receipts (ebarimt).

Customer Errors

Client Errors

Account and Terminal Errors

QR and Transaction Errors

Other Errors

Full Error Code Reference

A complete alphabetical listing of all QPay V2 error codes with their categories.

Troubleshooting

”AUTHENTICATION_FAILED” on every request

1. Verify QPAY_USERNAME and QPAY_PASSWORD are correct.
2. Make sure you are using the right base URL — sandbox credentials do not work on production, and vice versa.
3. Check that your merchant account is active by contacting QPay support.

”INVOICE_CODE_INVALID” when creating invoices

1. Confirm your QPAY_INVOICE_CODE value matches exactly what QPay provided.
2. Invoice codes are case-sensitive.
3. If you recently received new credentials, your old invoice code may be invalid.

”INVALID_AMOUNT” errors

1. Amount must be a positive number greater than zero.
2. Amount must meet QPay’s minimum threshold (varies by merchant configuration).
3. Do not send string values for the amount field — use a numeric type.

Timeout or network errors

1. Check your internet connection and firewall rules.
2. QPay API endpoints must be reachable from your server.
3. Consider increasing the HTTP client timeout (default is usually 30 seconds).
4. If the error persists, check QPay’s status  or contact support.

Token expiration issues

All SDKs handle token refresh automatically. If you are still seeing 401 errors:

1. Ensure your SDK is at the latest version.
2. Check that your system clock is synchronized (token expiry checks rely on accurate time).
3. If using manual token management, call refreshToken() before the access token expires.

Callback (webhook) not received

1. Verify your QPAY_CALLBACK_URL is a publicly accessible HTTPS URL.
2. Check that your server returns a 200 status code within a reasonable time.
3. Ensure your firewall allows incoming POST requests from QPay’s servers.
4. Use checkPayment as a fallback — always verify payment status server-side.