API errors and rate limits

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

{
  "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.
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:

Read the Retry-After response header.
Interpret its value as a delay in seconds.
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.

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:

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.

Authentication and scopes

Review key controls, account boundaries, expiry, and required scopes.

Protection changes

Review network mutations and their sync results before sending writes.

Getting started

Resources

Integration guides

API errors and rate limits

Error format

Status and code reference

Handle rate limits

Check the API boundary

Authentication and scopes

Protection changes

​Error format

​Status and code reference

​Handle rate limits

​Check the API boundary

​Related reference

Authentication and scopes

Protection changes

Error format

Status and code reference

Handle rate limits

Check the API boundary

Related reference