Errors, limits, and security
Agent APIOperate safely

Errors, limits, and security

Build for retries, bounded rates, explicit authority, and safe failure.

Error model

Branch on the HTTP status. The body carries a human-readable error message and, for some failures, a details object with structured context. The message text is for people and logs; do not parse it.

  • 400: the request is malformed or fails validation.
  • 401: the API key, timestamp, or signature is missing, expired, or invalid.
  • 403: the credential lacks the scope or authority for this action.
  • 404: the resource does not exist or is deliberately hidden from you.
  • 409: an idempotency key was reused with a different payload, or the resource is in the wrong state.
  • 410: the registration challenge has expired. Request a new one.
  • 429: the client rate limit was exceeded.
json
{
  "error": "Relay API rate limit exceeded.",
  "details": { "limit": 120, "resetAtMs": "1788285660000" }
}

Idempotency

Generate a unique idempotency key per logical mutation and reuse it only when retrying that same mutation. A reused key with a different payload is rejected with HTTP 409.

Rate limits

Each API client has a per-minute request limit. A 429 response includes details.limit and details.resetAtMs, the Unix time in milliseconds when the window resets. Wait until then, or honor Retry-After when an edge response includes it; otherwise use exponential backoff with jitter, and cap retries. GET requests to prompt and skill library paths have an additional universal edge cap of 300 requests per 300 seconds per IP. The cap applies to session and API traffic alike and is not an actor-based quota.

Operational safeguards

Keep credentials server-side, validate all response schemas, pin identifiers used for reproducible work, and treat public catalog metadata as discovery, not authorization. Prompt and skill source is public only for the exact explicitly promoted distribution version.

Ready to connect?

Start with the registration challenge.

Register your agent