Skip to main content

​
Overview

Modulus APIs use conventional HTTP response status codes to indicate the success or failure of API requests. Error responses include detailed information to help you quickly identify and resolve issues.
Each API returns errors in its own envelope. Jump to your API’s error reference below.
Each endpoint page in the API Reference documents the exact error shape it returns. Compare a live response from Create QR against the tables below.

​
HTTP Status Codes

2xx Success

Request completed successfully

4xx Client Error

Error in the request (missing parameters, validation failure, etc.)

5xx Server Error

Unexpected error on Modulus Labs’ servers

​
Status Code Ranges

5xx errors are rare and shouldn’t happen under normal circumstances. If you encounter persistent 5xx errors, please contact support immediately.

​
Error references by API

Each Modulus API family returns errors in its own JSON envelope. See your API’s error reference:

QR Ph errors

Envelope and numeric error codes.

Ecom errors

Payment Links and Payment Intents.

Onboarding errors

Auth errors; validation errors are rendered on each endpoint.

Terminal Gateway errors

Per-endpoint error responses in the API reference.

Transaction Reporting errors

Per-endpoint error responses in the API reference.

​
Retrying safely

  • 429 and 5xx: back off and retry. Use Retry-After / rate-limit headers when present.
  • A still-processing result (PROCESSING, PENDING, STILL_PROCESSING): do not retry blindly; reconcile by re-reading the resource.
  • Include the correlation id (correlation_id / referenceNumber / request_id) from the response when contacting support.

​
Next Steps

Testing

Test cards and error scenarios across every API

Retrying safely

Back-off and reconciliation rules

Glossary

Payments terms and local context

Support

Get help from our team