Skip to main content
Every error response from the 8bitedge API uses the same JSON envelope, regardless of the cause. Understanding this structure — and knowing what each error code means — lets you build resilient integrations that handle failures gracefully, distinguish between problems you can retry and problems you need to fix, and provide your users with meaningful feedback.

​
Error envelope

All errors return a top-level error object with the following fields: 
{
  "error": {
    "code": "string_code",
    "message": "Human-readable message.",
    "details": { ... }
  }
}
​
error.code
string
A stable, machine-readable string that identifies the error type. Use this field in your code to branch on specific failure conditions — never parse message programmatically.
​
error.message
string
A human-readable description of the error. Suitable for logging or surfacing to developers, but not intended for end-user display.
​
error.details
object
Optional. Provides context-specific information about the error — for example, which scope is missing, which rate window was exceeded, or how many batch items were received vs. allowed. The shape of details varies by error code.

​
Error codes reference

StatuscodeMeaning
401unauthorizedMissing, invalid, revoked, or expired API key
403account_inactiveYour organization or API client is not active
403insufficient_scopeYour key lacks the required scope for this endpoint
402quota_exceededMonthly quota exhausted on your plan
404not_foundThe requested resource does not exist
409idempotency_conflictSame idempotency key is still being processed
422validation_failedRequest body failed validation
422batch_too_largeBatch exceeds your plan’s max_batch_size
422idempotency_key_reuseIdempotency key reused with a different payload
429rate_limit_exceededPer-minute or per-day limit exceeded
501not_implementedEndpoint exists but logic is not yet available
500server_errorUnexpected server-side error

​
Per-error examples

The following examples show the exact response shape for the most common errors you are likely to encounter.

​
unauthorized — missing or invalid API key

Returned when you make a request without an Authorization header, or with a key that is invalid, revoked, or expired: 
{ "error": { "code": "unauthorized", "message": "Missing API key." } }
Ensure your request includes the Authorization: Bearer <token> header with a valid, active key.

​
insufficient_scope — key missing a required scope

Returned when your API key does not carry the scope required by the endpoint you are calling. The details.required_scope field tells you exactly which scope to add: 
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the required scope: games.read.",
    "details": { "required_scope": "games.read" }
  }
}
Issue a new API key with the appropriate scope, or contact your organization administrator.

​
rate_limit_exceeded — per-minute or per-day limit hit

Returned when you exhaust your plan’s request rate limit. The details.window field indicates whether the per-minute or per-day window was hit, and details.limit shows the threshold: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for the minute window.",
    "details": {
      "window": "minute",
      "limit": 120
    }
  }
}
Respect the Retry-After response header — it tells you exactly how many seconds to wait before retrying. See Plans & Limits for rate limit details by plan.

​
quota_exceeded — monthly quota exhausted

Returned when your plan’s monthly request quota has been fully consumed. No further requests are processed until the quota resets at the start of your next billing period: 
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. Upgrade your plan or wait for your quota to reset."
  }
}
Check GET /api/v1/me to see how much quota you have used and when it resets. Consider upgrading your plan if you consistently reach this limit.

​
batch_too_large — batch exceeds plan maximum

Returned when the number of items in a batch request exceeds your plan’s max_batch_size. The details object tells you both the maximum allowed and how many you submitted: 
{
  "error": {
    "code": "batch_too_large",
    "message": "The batch exceeds the maximum allowed size for your plan.",
    "details": {
      "max_items": 50,
      "received": 75
    }
  }
}
Split your batch into multiple smaller requests, each within the max_items limit for your plan.

​
Correlation IDs

Every response from the 8bitedge API — both successful responses and errors — includes an X-Request-Id header containing a UUID: 
X-Request-Id: 5f3c1e2a-9d4b-4f87-b3e1-7a02c5d09b21
This ID uniquely identifies the request in the API’s server-side logs. When you report an issue or open a support ticket, always include the X-Request-Id value from the response. It allows the 8bitedge team to look up the exact request, trace its execution path, and diagnose the problem quickly.
Retry strategy: Retry 429 errors after the number of seconds specified in the Retry-After header — the server calculates the exact wait time for you. Retry 5xx errors with exponential backoff and jitter, since they indicate transient server-side problems. Do not automatically retry 4xx errors (other than 409) — they indicate a client-side problem with your request that will not resolve on its own. For 409 idempotency_conflict, wait a few seconds and retry; the original request is still in progress and the stored response will be available shortly.