> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moduluslabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> QR Ph error envelope and codes

## Overview

The QR Ph API returns a standard JSON error object:

```json theme={null}
{
  "code": "10000013",
  "error": "Your API Key is incorrect.",
  "referenceNumber": "338e2710-8268-4afe-8ef9-9765b0b74688"
}
```

| Field             | Type   | Description                                                                     |
| ----------------- | ------ | ------------------------------------------------------------------------------- |
| `code`            | string | Machine-readable error code. **Branch on this**, not on `error`.                |
| `error`           | string | Human-readable message. Wording can change between releases.                    |
| `referenceNumber` | string | A generated support id for this occurrence. Include it when contacting support. |

<Note>
  Most failures return HTTP `400` even for auth problems: a validation layer converts non-HTTP errors to `400`. Only a missing authorization header or a malformed (non-Base64) key returns `401`. There is no `403` or `500` on this API.
</Note>

## Error codes

These are the codes reachable on `POST /v1/pay/qr`. Match on `code`.

| Code       | HTTP | Message                                                                             | What to do                                                                      |
| ---------- | ---- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `10000003` | 400  | Account does not exist.                                                             | Verify you are using the correct sandbox credentials.                           |
| `10000006` | 400  | Your API Key is incorrect.                                                          | Check the secret key you send as the Basic-auth username.                       |
| `10000008` | 400  | Your API Key has expired.                                                           | Request a new key from support.                                                 |
| `10000009` | 400  | Your API Key has been revoked.                                                      | Request a new key from support.                                                 |
| `10000010` | 400  | Your API Key has been suspended. Please contact support.                            | Contact [support@moduluslabs.io](mailto:support@moduluslabs.io).                |
| `10000012` | 400  | The resource cannot be accessed with the provided API key.                          | Use a key with access to this operation.                                        |
| `10000013` | 400  | Your API Key is incorrect.                                                          | Recheck the key and how it is encoded into the `Authorization` header.          |
| `10000016` | 401  | Missing authorization header.                                                       | Send `Authorization: Basic <base64(secret_key:)>`.                              |
| `10000019` | 401  | Invalid authentication credentials. Key provided is not a valid Base64 encoded key. | Base64-encode `secret_key:` (note the trailing colon).                          |
| `60000001` | 400  | An unexpected error occurred. Please contact Support if the issue continues.        | Retry with backoff; if it persists, contact support with the `referenceNumber`. |

## Handling errors

```javascript theme={null}
const res = await fetch(url, options);
if (!res.ok) {
  const { code, error, referenceNumber } = await res.json();
  switch (code) {
    case '10000016':
    case '10000019':
      // fix the Authorization header
      break;
    case '60000001':
      // transient - retry with backoff
      break;
    default:
      // credential/permission problem - surface `error`, log `referenceNumber`
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/qr/authentication">
    How Basic auth and the secret key work
  </Card>

  <Card title="Testing" icon="flask" href="/docs/testing">
    Test error scenarios in sandbox
  </Card>

  <Card title="Global errors" icon="triangle-exclamation" href="/docs/errors">
    HTTP status ranges and retry rules
  </Card>

  <Card title="Support" icon="envelope" href="mailto:support@moduluslabs.io">
    Get help with an error
  </Card>
</CardGroup>