API basics

Errors and request IDs

Handle validation, permission, rate limit, and service errors predictably.
View as Markdown

Alpha returns JSON errors with a stable code, a human-readable message, and a request ID.

1{
2  "error": {
3    "code": "invalid_request",
4    "message": "The JSON body must be an object.",
5    "requestId": "b4db1e4f-0f4e-4f55-9471-a7bf50f9e6b1"
6  }
7}
StatusMeaningWhat to do
400Invalid body, argument, or vault selectionCorrect the request and do not retry unchanged
401Missing, invalid, expired, or revoked bearer tokenRefresh OAuth or replace the API key
403The user or key role cannot perform the actionRequest the correct vault role
404Tool or resource not foundRefresh the tool catalog or resource ID
429Rate limit reachedWait for Retry-After, then retry with backoff
5xxTemporary service failureRetry with bounded exponential backoff

Request IDs

Every response includes X-Request-Id. You can also send your own value, up to 120 characters, in the request header. Use a unique ID for each attempt.

1X-Request-Id: order-review-2026-09-02-001

Alpha stores the ID with its shared API and MCP audit record. Secret values and sensitive tool arguments are redacted before storage.

Rate limits

Current API limits are 240 requests per minute per credential and 600 requests per minute per source IP. SDKs retry common transient responses, but your application should still bound total retries.