Errors And Rate Limits

Skunivo returns structured errors so integrations can handle expected failures programmatically and preserve enough context for support.

Error Shape

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope.",
    "requestId": "req_123",
    "details": {
      "requiredScope": "inventory:write"
    }
  }
}

Use error.code for control flow. Use requestId for logs and support tickets.

Common Codes

Code	Meaning	Client action
VALIDATION_ERROR	The request payload or parameters are invalid.	Fix the request before retrying.
UNAUTHORIZED	The API key is missing or invalid.	Check credential configuration.
FORBIDDEN	The key lacks the required scope or organization access.	Adjust scopes or organization selection.
NOT_FOUND	The resource does not exist in the organization/environment.	Check ids and environment.
IDEMPOTENCY_CONFLICT	The key was reused with a different payload.	Generate a new key only for a new logical operation.
INSUFFICIENT_STOCK	The requested stock operation cannot be satisfied.	Surface the business failure or retry after stock changes.
CONCURRENCY_CONFLICT	Concurrent changes conflicted.	Re-read state and retry with the same idempotency key when the business operation is unchanged.
RATE_LIMITED	The integration exceeded a rate limit.	Respect Retry-After and back off.
PLAN_LIMIT_EXCEEDED	A monthly quota, resource limit or plan capability is exhausted.	Inspect details.entitlementKey, stop automatic retries and direct the organization to its billing page.
INTERNAL_ERROR	Unexpected platform failure.	Retry with backoff if the operation is safe and idempotent.

Rate Limits

Rate limits protect the platform and keep integrations predictable. Responses can include rate limit headers and Retry-After.

Commercial quotas

Rate limits and plan quotas are separate controls:

• RATE_LIMITED protects short traffic bursts and normally uses 429.
• PLAN_LIMIT_EXCEEDED enforces plan limits and uses 403.
• api_requests counts every authorized API-key request that reaches billing, including client retries.
• billable_inventory_operations counts one successful inventory business command, regardless of lines, quantities, serials, lots or ledger movements.

Failed and rolled-back inventory commands do not consume inventory-operation quota. Replaying an already completed idempotency key does not consume another inventory operation, although the retry still counts as an API request. Releases, cancellations, closes, expirations and system consistency work remain available when the operation quota is exhausted.

Monthly counters use calendar months in UTC and remain separate for the test and live environments. Numeric values in plan-limit error details are decimal strings.

When limited:

1. Stop immediate retries.
2. Respect Retry-After when present.
3. Retry with exponential backoff and jitter.
4. Keep the original Idempotency-Key for the same write operation.
5. Log the requestId.

Retry Guidance

Retry transient failures such as network timeouts, RATE_LIMITED, selected 5xx responses and concurrency conflicts after re-reading state.

Do not blindly retry validation, authorization or insufficient stock errors. Those usually require a changed request, changed permissions or changed inventory state.