Modem Pay returns errors in a consistent JSON format to make it easy to handle issues in your application. Each error includes a simple message explaining the issue, with HTTP status codes indicating the type of error.

​
Error Format

All error responses follow this structure: 
{
  "message": "Description of the error",
  "statusCode": "Error status code"
}

​
Common Status Codes

  • 4xx Client Errors: These indicate issues in the request sent to the server.
    • 400 Bad Request: The request was invalid or missing required fields.
    • 401 Unauthorized: Missing or invalid API key.
    • 403 Forbidden: You don’t have permission to access this resource.
    • 404 Not Found: The requested resource doesn’t exist or was entered incorrectly.
    • 405 Method Not Allowed: The HTTP method used is not supported for this endpoint.
    • 422 Unprocessable Entity: The request was well-formed but contained semantic errors.
    • 427 Too Many Requests: You’ve exceeded the rate limit for API requests.
  • 5xx Server Errors: These signify an issue on Modem Pay’s end.
    • 500 Internal Server Error: General server error; retry the request or contact support if it persists.

​
Handling Errors

Check the message field in the response to understand the cause of the error. If the status code is 400 or higher, review your request parameters and API key to ensure they meet Modem Pay’s requirements.

​
Error Retries

Modem Pay offers automatic retry handling for certain types of errors. By default, Modem Pay retries up to three times if a request fails due to transient issues, such as network errors or temporary server overloads. This is configurable via the maxRetries option, which you can set during initialization: 
const modempay = new ModemPay(process.env.MODEM_API_KEY, {
  maxRetries: 3, // Sets the maximum number of retry attempts
});

​
When Retries Occur

Retries are triggered for errors that are likely temporary, typically with 5xx server errors. Each retry is delayed slightly to give the server time to recover, helping ensure more reliable payment handling.

​
Adjusting or Disabling Retries

To reduce or increase the retry count, simply adjust the maxRetries value. Setting it to 0 disables retries entirely: 
const modempay = new ModemPay(process.env.MODEM_API_KEY, {
  maxRetries: 0, // Disables retries
});
To disable error retry logs, add RETRY_LOGGING=false to your .env file. This will suppress the retry attempt logs while still performing the retries.

​
Request Timeouts

Modem Pay lets you configure request timeouts to prevent your application from waiting indefinitely for a response. By default, requests will time out after 60 seconds (1 minute). You can easily customize the timeout duration by specifying the timeout option (in seconds) when initializing the Modem Pay client: 
const modempay = new ModemPay(process.env.MODEM_API_KEY, {
  timeout: 20, // Timeout set to 20 seconds
});

​
Rate Limiting

To maintain the stability and security of our platform, Modem Pay enforces rate limiting on all API requests. Each API key is allowed up to 100 consecutive requests within a 15-minute rolling window. If this limit is exceeded, further requests will be temporarily blocked until the window resets. We recommend implementing retries with exponential backoff and monitoring your request patterns to stay within the allowed limits. If your application requires a higher throughput, please contact us at info@modempay.com to discuss increased rate limits based on your business needs.