Errors

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

Status Code	Meaning	What to Do
200-299	Success	Request worked as expected
400-499	Client Error	Check your request parameters and credentials
500-599	Server Error	Contact Modulus Labs support

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:

{
  "code": "10000002",
  "error": "Account is disabled. Please contact support for assistance.",
  "referenceNumber": "338e2710-8268-4afe-8ef9-9765b0b74688"
}

Error Object Properties

Field	Type	Description
`code`	string	Machine-readable error code for programmatic handling
`error`	string	Human-readable error message with details
`referenceNumber`	string	Unique identifier for this error occurrence (use when contacting support)

Error Codes Reference

Account & Authentication Errors (10000001-10000015)

10000001 - Account Locked

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

{
  "code": "10000001",
  "error": "Account Locked",
  "referenceNumber": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

10000002 - Account Not Active

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

{
  "code": "10000002",
  "error": "Account is disabled. Please contact support for assistance.",
  "referenceNumber": "338e2710-8268-4afe-8ef9-9765b0b74688"
}

10000003 - Account Not Found

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

{
  "code": "10000003",
  "error": "Account not found",
  "referenceNumber": "b2c3d4e5-f6g7-8901-bcde-f12345678901"
}

10000006 - API Key Not Found

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

{
  "code": "10000006",
  "error": "API Key not found",
  "referenceNumber": "c3d4e5f6-g7h8-9012-cdef-123456789012"
}

10000008 - API Key Expired

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

{
  "code": "10000008",
  "error": "API Key expired",
  "referenceNumber": "d4e5f6g7-h8i9-0123-defg-234567890123"
}

10000009 - API Key Revoked

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

{
  "code": "10000009",
  "error": "API Key revoked",
  "referenceNumber": "e5f6g7h8-i9j0-1234-efgh-345678901234"
}

10000010 - API Key Suspended

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

{
  "code": "10000010",
  "error": "API Key suspended",
  "referenceNumber": "f6g7h8i9-j0k1-2345-fghi-456789012345"
}

10000011 - API Key Deleted

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

{
  "code": "10000011",
  "error": "API Key deleted",
  "referenceNumber": "g7h8i9j0-k1l2-3456-ghij-567890123456"
}

10000012 - Unauthorized Action

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

{
  "code": "10000012",
  "error": "Unauthorized to perform action",
  "referenceNumber": "h8i9j0k1-l2m3-4567-hijk-678901234567"
}

10000013 - Invalid API Key

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

{
  "code": "10000013",
  "error": "Invalid API Key",
  "referenceNumber": "i9j0k1l2-m3n4-5678-ijkl-789012345678"
}

10000015 - Insufficient Permissions

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

{
  "code": "10000015",
  "error": "Insufficient permissions",
  "referenceNumber": "j0k1l2m3-n4o5-6789-jklm-890123456789"
}

Error Response Types

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

Authenticated Errors
Unauthenticated Errors

Declined Requests (Authenticated)

When authenticated but the request is declined, errors are returned as encrypted JWE tokens:

{
  "Token": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0..."
}

After decryption:

{
  "code": "10000015",
  "error": "Insufficient permissions",
  "referenceNumber": "abc123-def456-ghi789"
}

You must decrypt these responses using your Encryption Key. See the Encryption Guide for details.

Unauthorized Requests (Not Authenticated)

When authentication fails, errors are returned unencrypted as plain JSON:

{
  "code": "10000013",
  "error": "Invalid API Key",
  "referenceNumber": "338e2710-8268-4afe-8ef9-9765b0b74688"
}

Authentication errors bypass encryption since the credentials are invalid. Handle these separately in your code.

Handling Errors in Code

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

const axios = require('axios');
const jose = require('jose');

async function handleApiCall() {
  try {
    const response = await axios.post(
      'https://qrph.sbx.moduluslabs.io/v1/pay/qr',
      { Token: encryptedPayload },
      {
        auth: { username: secretKey, password: '' },
        headers: { 'Content-Type': 'application/json' }
      }
    );

    // Check if response contains Token (encrypted)
    if (response.data.Token) {
      const { plaintext } = await jose.compactDecrypt(
        response.data.Token,
        encryptionKey
      );
      const data = JSON.parse(new TextDecoder().decode(plaintext));

      // Check if decrypted data is an error
      if (data.code) {
        console.error(`Error ${data.code}: ${data.error}`);
        console.error(`Reference: ${data.referenceNumber}`);
        return null;
      }

      return data;
    }

    return response.data;

  } catch (error) {
    if (error.response) {
      // HTTP error response
      const { status, data } = error.response;

      if (data.code) {
        // Unencrypted error (authentication failure)
        console.error(`Auth Error ${data.code}: ${data.error}`);
        console.error(`Reference: ${data.referenceNumber}`);
      } else {
        console.error(`HTTP ${status}: ${JSON.stringify(data)}`);
      }
    } else {
      // Network or other error
      console.error('Request failed:', error.message);
    }
    throw error;
  }
}

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

curl https://qrph.sbx.moduluslabs.io/ping \
  -u invalid_key:

# Response:
# {
#   "code": "10000006",
#   "error": "API Key not found",
#   "referenceNumber": "..."
# }

Test with Malformed Request

curl https://qrph.sbx.moduluslabs.io/v1/pay/qr \
  -u sk_valid_key: \
  -H "Content-Type: application/json" \
  -d '{"Token": "invalid_jwe_token"}'

Getting Help

Check This Documentation

Review the error code and common solutions above

Test in Sandbox

Reproduce the error in the sandbox environment

Gather Information

Collect:

Error code
Reference number
Full request/response (remove sensitive data)
Timestamp

Contact Support

Email [email protected] with the gathered information

Reference numbers are crucial - always include them when contacting support for faster resolution.

QR API

Onboarding API

Webhooks API

Shared Resources

Overview

HTTP Status Codes

2xx Success

4xx Client Error

5xx Server Error

Status Code Ranges

Error Response Format

Error Object Properties

Error Codes Reference

Account & Authentication Errors (10000001-10000015)

Error Response Types

Declined Requests (Authenticated)

Unauthorized Requests (Not Authenticated)

Handling Errors in Code

Best Practices

Log Reference Numbers

Implement Retry Logic

Handle Both Formats

Monitor Error Rates

Graceful Degradation

User-Friendly Messages

Testing Errors

Test with Invalid Credentials

Test with Malformed Request

Getting Help

Next Steps

Testing Guide

Quickstart

QR API

Onboarding API

Webhooks API

Shared Resources

​Overview

​HTTP Status Codes

2xx Success

4xx Client Error

5xx Server Error

​Status Code Ranges

​Error Response Format

​Error Object Properties

​Error Codes Reference

​Account & Authentication Errors (10000001-10000015)

​Error Response Types

​Declined Requests (Authenticated)

​Unauthorized Requests (Not Authenticated)

​Handling Errors in Code

​Best Practices

Log Reference Numbers

Implement Retry Logic

Handle Both Formats

Monitor Error Rates

Graceful Degradation

User-Friendly Messages

​Testing Errors

​Test with Invalid Credentials

​Test with Malformed Request

​Getting Help

​Next Steps

Testing Guide

Quickstart

Overview

HTTP Status Codes

Status Code Ranges

Error Response Format

Error Object Properties

Error Codes Reference

Account & Authentication Errors (10000001-10000015)

Error Response Types

Declined Requests (Authenticated)

Unauthorized Requests (Not Authenticated)

Handling Errors in Code

Best Practices

Testing Errors

Test with Invalid Credentials

Test with Malformed Request

Getting Help

Next Steps