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

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

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.

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.

​

Related reference

Authentication and scopes

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

Protection changes

Review network mutations and their sync results before sending writes.