Skip to main content

Overview

The Modulus Labs QR API uses 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.

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 Response Format

The API returns a standard JSON error object:

Error Object Properties

Error Codes Reference

Account & Authentication Errors (10000001-10000015)

Meaning: Your account has been locked due to security concernsCommon Causes:
  • Multiple failed authentication attempts
  • Suspicious activity detected
  • Manual lock by administrator
Solution:
  • Contact Modulus Labs support to unlock your account
  • Provide the reference number from the error response
  • Review account security after unlocking
Meaning: Your account is not active or has been disabledCommon Causes:
  • Account pending approval
  • Subscription expired
  • Account manually disabled
Solution:
  • Check your email for activation instructions
  • Verify your subscription status
  • Contact support if the issue persists
Meaning: The account associated with the credentials doesn’t existCommon Causes:
  • Using credentials from deleted account
  • Typo in Secret Key
  • Wrong environment (sandbox vs. production)
Solution:
  • Verify your Secret Key is correct
  • Ensure you’re using the right environment
  • Contact support if you believe this is an error
Meaning: The Secret Key provided doesn’t exist in the systemCommon Causes:
  • Incorrect Secret Key
  • Key was deleted
  • Copy/paste error
Solution:
  • Double-check your Secret Key
  • Generate a new key if needed
  • Verify key is properly stored in environment variables
Meaning: Your Secret Key has expiredCommon Causes:
  • Key exceeded its validity period
  • Automatic expiration policy
Solution:
  • Generate a new Secret Key
  • Update your application configuration
  • Implement key rotation strategy
Meaning: Your Secret Key has been revokedCommon Causes:
  • Key compromised and manually revoked
  • Revoked during key rotation
  • Security incident
Solution:
  • Generate a new Secret Key immediately
  • Review security logs
  • Contact support if unexpected
Meaning: Your Secret Key is temporarily suspendedCommon Causes:
  • Suspicious activity
  • Policy violation
  • Payment issue
Solution:
  • Contact support to resolve the suspension
  • Provide reference number
  • Address the underlying issue
Meaning: The Secret Key has been permanently deletedCommon Causes:
  • Manual deletion
  • Account cleanup
  • Security incident response
Solution:
  • Generate a new Secret Key
  • Update application configuration
  • Cannot recover deleted keys
Meaning: Not authorized to perform this actionCommon Causes:
  • Insufficient account permissions
  • API endpoint not available for your account type
  • Incorrect credentials
Solution:
  • Verify your account has the required permissions
  • Check if you’re using the correct endpoint
  • Contact support to upgrade permissions
Meaning: The Secret Key format is invalidCommon Causes:
  • Malformed key string
  • Incorrect encoding
  • Corrupted key during storage/retrieval
Solution:
  • Verify the Secret Key format
  • Ensure no extra spaces or characters
  • Re-copy the key from secure storage
Meaning: API key doesn’t have required permissions for this operationCommon Causes:
  • Read-only key used for write operation
  • Key lacks specific permission
  • Permission not assigned to account
Solution:
  • Use an API key with appropriate permissions
  • Request permission upgrade from support
  • Review key permissions in dashboard

Error Response Types

The API returns errors in different formats depending on the authentication status:

Declined Requests (Authenticated)

When authenticated but the request is declined, errors are returned as encrypted JWE tokens:
After decryption:
You must decrypt these responses using your Encryption Key. See the Encryption Guide for details.

Handling Errors in Code

Here’s how to properly handle errors in your application:

Best Practices

Log Reference Numbers

Always log the referenceNumber - it’s essential for troubleshooting with support

Implement Retry Logic

Implement exponential backoff for 5xx errors and rate limit errors

Handle Both Formats

Check for both encrypted and unencrypted error responses

Monitor Error Rates

Track error rates to identify integration issues early

Graceful Degradation

Provide fallback options when API calls fail

User-Friendly Messages

Translate technical errors into user-friendly messages

Testing Errors

You can simulate errors in the sandbox environment to test your error handling:

Test with Invalid Credentials

Test with Malformed Request

Getting Help

1

Check This Documentation

Review the error code and common solutions above
2

Test in Sandbox

Reproduce the error in the sandbox environment
3

Gather Information

Collect:
  • Error code
  • Reference number
  • Full request/response (remove sensitive data)
  • Timestamp
4

Contact Support

Email support@moduluslabs.io with the gathered information
Reference numbers are crucial - always include them when contacting support for faster resolution.

Next Steps

Testing Guide

Learn how to test error scenarios in sandbox

Quickstart

Build a complete integration with proper error handling