Every error response from the MiniMoth API has a stable `code` field you can use in your code to handle specific cases. Codes will not change — you can safely switch on them.

```json
{
  "error": "Human-readable message",
  "code": "STABLE_CODE",
  "request_id": "req_..."
}
```

## Authentication

| Code | Status | Description |
|---|---|---|
| `MISSING_API_KEY` | 401 | No `X-Api-Key` header was sent. |
| `INVALID_API_KEY` | 401 | The API key is not recognised. Check the key in your project settings. |

## Validation

| Code | Status | Description |
|---|---|---|
| `INVALID_PHONE` | 422 | Phone number is not a valid Indian mobile number (10 digits starting with 6–9, with or without `+91`), and not a number in a supported international market either. See [International WhatsApp OTP](/docs/international-whatsapp) for supported markets. |
| `INVALID_OTP_CODE` | 422 | The `code` field must be exactly 6 digits. |
| `MISSING_ACCESS_TOKEN` | 422 | The request body is missing the `access_token` field. |
| `MISSING_REFRESH_TOKEN` | 422 | The request body is missing the `refresh_token` field. |

## OTP

| Code | Status | Description |
|---|---|---|
| `OTP_RATE_LIMITED` | 429 | Too many OTPs requested for this number. Limit is 3 per phone per 10 minutes. |
| `OTP_NOT_FOUND` | 400 | No active OTP exists for this phone number. It may have expired (10 min TTL) or already been used. |
| `INVALID_OTP` | 400 | The OTP code is incorrect. |
| `VERIFY_RATE_LIMITED` | 429 | Too many incorrect attempts for this OTP. The OTP is now locked — request a new one. |
| `SMS_FAILED` | 500 | Both WhatsApp and SMS fallback delivery failed. The charge was not applied. Retry after a moment. |
| `OTP_REQUEST_NOT_FOUND` | 404 | No OTP request found with that ID, or it does not belong to this project. Returned by `GET /v1/otp/status/:otp_id`. |

## International markets

| Code | Status | Description |
|---|---|---|
| `REGION_NOT_ENABLED` | 403 | The phone number's market exists, but this project hasn't turned it on yet. Enable it from the project's International WhatsApp OTP card in the dashboard, which shows the rate before you turn it on. See [International WhatsApp OTP](/docs/international-whatsapp). |
| `INTERNATIONAL_WHATSAPP_FAILED` | 502 | A real WhatsApp delivery attempt to an international number failed. There is no SMS fallback for these numbers. The message states whether the charge was refunded — it always is unless the refund itself failed (rare; contact support if it persists). |
| `INTERNATIONAL_WHATSAPP_BLOCKED` | 502 | This number has had too many recent WhatsApp delivery failures and is temporarily blocked — no delivery was attempted and no charge was made for this call. The block clears on its own once the window passes without a new real failure. |
| `WHATSAPP_ACCOUNT_REQUIRED` | 403 | This project has no usable own-WhatsApp connection (not connected, branded delivery off, or template not approved), so US/EU numbers cannot be delivered. Connect your own WhatsApp Business Account and turn on branded delivery in the project's WhatsApp settings. No OTP was sent and no charge was applied. |

## Billing

| Code | Status | Description |
|---|---|---|
| `INSUFFICIENT_BALANCE` | 402 | Wallet balance is too low to send an OTP. Top up from the dashboard. No OTP was sent and no charge was applied. |
| `SPEND_CAP_REACHED` | 402 | Your wallet can cover this OTP, but sending it would exceed your monthly spend cap. Topping up does not help — raise the cap under Billing in the dashboard (or wait for the monthly reset on the 1st). No OTP was sent and no charge was applied. |

## Session

| Code | Status | Description |
|---|---|---|
| `SESSION_EXPIRED` | 401 | The refresh token has expired or is invalid. The user must re-authenticate. |
| `INVALID_ACCESS_TOKEN` | 401 | The access token is invalid or expired. Returned by `session/logout` when called with an expired token — refresh the session first, then retry the logout. |
| `RATE_LIMITED` | 429 | General rate limit exceeded — 1000 requests per minute per API key. Back off and retry. |

## Identity

| Code | Status | Description |
|---|---|---|
| `IDENTITY_DELETE_DISABLED` | 403 | Identity deletion isn't turned on for this project. Enable it from the project's Identity settings card in the dashboard. See [Identity](/docs/identity#deleting-an-identity). |
| `IDENTITY_LOOKUP_DISABLED` | 403 | Identity lookup isn't turned on for this project. Enable it from the project's Identity settings card in the dashboard. See [Identity](/docs/identity#looking-up-an-identity). |
| `IDENTITY_NOT_FOUND` | 404 | No identity with that id, or it belongs to a different project. |

## Node.js SDK

[@minimoth/sdk-node](https://www.npmjs.com/package/@minimoth/sdk-node) surfaces every code above as-is via `err.code` — plus a few additional codes on top of the API's, for conditions the SDK catches locally before or instead of a network call.

| Code | Status | Description |
|---|---|---|
| `INVALID_PHONE` | — | SDK-only trigger, thrown client-side before any request is sent: an empty or non-string phone number. Spaces and hyphens are stripped, not rejected — `+1-2025551234` and `+12025551234` both work. Distinct from the API's own `INVALID_PHONE` (422) above, which fires server-side on a malformed but well-formatted number. |
| `NETWORK_ERROR` | — | The underlying `fetch()` call threw — the network was unreachable or the request otherwise never completed. |
| `UNKNOWN_ERROR` | — | The API response had no error code at all — an unparseable body, or a response shape that never included one. Check `err.statusCode` for the raw HTTP status. |

---

Full documentation index: https://minimoth.dev/llms.txt
