Rate Limits and Errors

Every request to the public surface is counted against the source IP address. These limits sit alongside the per-token token-bucket and catch rapid-fire abuse from a single host before token revocation can propagate. The api uses Fastify's trust-proxy mode, so a client behind a reverse proxy is identified by its real IP, not the proxy's.

When an IP exceeds its budget, the api returns 429 RATE_LIMITED with a Retry-After header in seconds. Standard X-RateLimit-Limit and X-RateLimit-Remaining headers are set on every /api/public/v1/* response so clients can self-pace without waiting for a 429.

Each token holds a token-bucket per risk tier. A read tool and a destructive tool do not share the same bucket. Aggregate caps per user per guild sit one tier above the per-token limit, so a single user with three tokens cannot multiply their destructive budget by three.

A typical Pro guild driving the API from a single integration will never see a per-token 429 under normal use. There are no published per-tool quotas in v1. The tier of a given endpoint or MCP tool is derived from endpoint-policy.ts and tool-policy.ts, which are the canonical source for that mapping.

Every error from the public surface uses the same shape. REST returns the envelope with the matching HTTP status (401, 403, 404, 409, 422, 429, 5xx). The MCP server returns the same envelope inside the tool result body. Clients can write a single error handler and reuse it for both surfaces.

{
  "error": {
    "code": "RE_AUTH_REQUIRED",
    "message": "Re-authentication is required before running this operation.",
    "retryable": false,
    "request_id": "req_01HW9X8Y7Z6V5T",
    "details": {
      "reauth_url": "https://arkanis.gg/dashboard/123/settings/api-mcp#approve-window"
    }
  }
}

Field reference:

• code: machine-readable error code. Drawn from the enum below.
• message: human-readable explanation. Safe to surface to operators, never to an end user.
• retryable: when true, the operation can be retried with backoff. When false, the client needs to fix something first.
• request_id: trace id for the request. Include it when reporting issues to support.
• details: optional structured payload that varies by code. The shape per code is documented below.

The retryable flag is the only thing a client needs to inspect to decide whether to retry. Codes that are transient set retryable: true. Codes that need a client-side fix set retryable: false.

For retryable codes, honour Retry-After when present. Otherwise use exponential backoff starting at 1 second, doubling, capped at 30 seconds, with a small jitter.

The full enum of error codes the public surface can emit. The list is locked at v1 and lives in api/src/lib/public/error-envelope.ts as PUBLIC_ERROR_CODES.

Returned with HTTP 429 when the per-IP or per-token budget is exhausted. The Retry-After header carries the wait duration in seconds.

$ curl -i https://api.arkanis.gg/api/public/v1/strikes \
    -H "Authorization: Bearer arkpat_..."

HTTP/2 429
content-type: application/json
retry-after: 47
x-ratelimit-limit: 600
x-ratelimit-remaining: 0

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 47s.",
    "retryable": true,
    "request_id": "req_01HW9X8Y7Z6V5T"
  }
}

Wait the suggested cooldown and retry. Persistent 429s on a token point at a runaway loop on the client; an integration burning the destructive budget every minute is a sign of misconfigured automation, not a tuning problem.

The token is valid, but its capability snapshot does not include the capability required by the endpoint. Capabilities are inherited from the issuing user at token-creation time and re-checked on every call. If the issuer's capabilities changed after the token was issued, a new token is needed.

HTTP/2 403
content-type: application/json

{
  "error": {
    "code": "CAPABILITY_DENIED",
    "message": "Missing capability: enforcement_strike_add.",
    "retryable": false,
    "request_id": "req_01HW9X8Y7Z6V5T",
    "details": { "missing": ["enforcement_strike_add"] }
  }
}

The fix is to issue a fresh token from a user who currently holds the missing capability, or to adjust the role configuration in the dashboard and re-issue. Do not retry the same call with the same token — the result will not change.

Destructive operations require an open re-auth window. The default window is 15 minutes, opened by clicking Approve next destructive action in the dashboard. Outside the window, destructive calls return this envelope with a reauth_url pointing at the dashboard.

HTTP/2 403
content-type: application/json

{
  "error": {
    "code": "RE_AUTH_REQUIRED",
    "message": "Re-authentication is required before running this operation.",
    "retryable": false,
    "request_id": "req_01HW9X8Y7Z6V5T",
    "details": {
      "reauth_url": "https://arkanis.gg/dashboard/123/settings/api-mcp#approve-window"
    }
  }
}

For fully scripted workflows, an owner can also open the window via the authenticated dashboard API at POST /api-tokens/{tokenId}/reauth-window. The window then applies to the next destructive call from any client holding that token. See Destructive Actions for the full flow.

Destructive operations require a sentinel string in the _confirmation body field. The string must exactly match the template for the operation, with placeholders substituted using the caller's actual arguments. The api returns the expected formats in details so a script can self-correct.

HTTP/2 422
content-type: application/json

{
  "error": {
    "code": "INVALID_CONFIRMATION",
    "message": "Confirmation string does not match the expected sentinel for this action.",
    "retryable": false,
    "request_id": "req_01HW9X8Y7Z6V5T",
    "details": {
      "expected_format": "BAN USER {user_id} IN GUILD {guildId} {PERMANENT|DURATION N}",
      "expected_concrete": "BAN USER 123456789012345678 IN GUILD 987654321098765432 PERMANENT"
    }
  }
}

Set _confirmation to expected_concrete and retry. The sentinel is case-sensitive and whitespace-sensitive. The full sentinel catalog lives in Destructive Actions.

The token was revoked by its issuer, by a guild owner, or by an automated guard such as a downgrade off Pro. The dashboard records the revocation event in the audit log. Once revoked, a token is unusable.

HTTP/2 401
content-type: application/json

{
  "error": {
    "code": "TOKEN_REVOKED",
    "message": "This token has been revoked.",
    "retryable": false,
    "request_id": "req_01HW9X8Y7Z6V5T"
  }
}

Issue a new token from the dashboard and update any clients that still hold the old one. Do not attempt to revive a revoked token; revocation is final.