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

# API errors and rate limits

> Handle Orbitel Shield API authentication, authorization, validation, and rate-limit errors using structured JSON error codes and Retry-After.

Orbitel Shield API errors include an HTTP status and a structured JSON error. Use `error.code` to distinguish authentication, permissions, missing resources, invalid bodies, and rate limits.

## Error format

```json theme={null}
{
  "error": {
    "code": "missing_scope",
    "message": "..."
  }
}
```

The message above is a placeholder, not an exact server message. Validation failures also include `error.fields`, which names the invalid fields and what is wrong. The supplied specification does not define the exact shape of `error.fields`.

## Status and code reference

| HTTP status | Error code | Meaning and next action |
| - | - | - |
| 401 | `unauthorized`, `invalid_api_key` | No key was supplied, or it is unknown, revoked, or expired. Check the bearer header and key validity. |
| 401 | `api_key_not_accepted` | A key was sent to a panel endpoint. Use the public API under `/api/v1/public`. |
| 403 | `missing_scope` | The key lacks the scope required by this endpoint. Review the [scope table](https://docs.orbitelshield.com/api-reference/overview.md#scopes). |
| 403 | `ip_not_allowed` | The source IP is outside the key's allowed list. Check the address your integration actually sends from. |
| 404 | `not_found` | The item does not exist or belongs to a different account. Check the resource ID and account. |
| 405 | `method_not_allowed` | This area is read only over the API. Use a documented method or complete the action in the panel. |
| 415 | `unsupported_media_type` | Send request bodies as `application/json`. |
| 422 | `validation_failed` | The body did not validate. Inspect `error.fields` and correct the named fields. |
| 429 | `rate_limited` | Too many requests. Wait for the number of seconds in `Retry-After`. |

## Handle rate limits

Each key allows **120 requests per minute**, including at most **30 requests that change something**. The write limit does not increase the total allowance to 150.

When a `429` response arrives:

1. Read the `Retry-After` response header.
2. Interpret its value as a delay in seconds.
3. Wait for that delay before making another request with the key.

Repeated bad keys from a single address are blocked for **10 minutes**. Resolve the authentication error instead of repeatedly trying the same invalid key.

> [!WARNING]
>
> Protection changes apply to the network immediately. The supplied specification does not define idempotency or automatic retry behavior for write requests. Do not assume blindly repeating a create or delete request is safe.

## Check the API boundary

API keys are accepted only under this base URL:

```text theme={null}
https://portal.orbitelshield.com/api/v1/public
```

A signed-in browser session is not API authentication. Likewise, an API key cannot authorize panel pages, account settings, billing actions, or the admin area. Invoice read endpoints remain accessible with `invoices:read`; paying an invoice and applying credit stay in the panel.

## Related reference

> [card] [Authentication and scopes](https://docs.orbitelshield.com/api-reference/overview.md)
>
> Review key controls, account boundaries, expiry, and required scopes.

> [card] [Protection changes](https://docs.orbitelshield.com/api-reference/protection-changes.md)
>
> Review network mutations and their sync results before sending writes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.