Public agent API / v1

Errors and retries

Check the HTTP status first, then read the error body. Authentication and origin checks have their own response shapes.

Tool and request errors

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later.",
    "retryAfter": 5
  }
}

This is an illustrative rate-limit response. retryAfter is optional and measured in seconds; when supplied for HTTP 429, the response also sets Retry-After. Exact messages can vary.

Public API errors and recovery
HTTP	Code or message	Next step
400	INVALID_ARGUMENTS	Check parameters and request fields.
401	invalid_token	Authorize again using the WWW-Authenticate challenge.
403	Invalid request origin	Send browser writes from an allowed origin.
404	ASSET_NOT_FOUND	Check the item ID and the signed-in account.
413	PAGE_TOO_LARGE / DETAIL_TOO_LARGE	Request fewer items or omit geometry.
429	RATE_LIMITED	Wait for Retry-After before retrying.
500	INTERNAL_ERROR / UNKNOWN_OPERATION	An unexpected server failure occurred.
502	PROJECT_READ_FAILED / ASSET_READ_FAILED / PROJECT_CREATE_FAILED / BLOCK_CREATE_FAILED	The backing operation failed. Check state before repeating a write.
503	MCP_DISABLED / CATALOG_UNAVAILABLE	The agent surface or catalog is temporarily unavailable.

Authentication and origin errors

HTTP 401 uses the OAuth challenge body below, with a WWW-Authenticate header pointing to protected-resource metadata:

{"error":"invalid_token","error_description":"A valid OAuth access token is required."}

The cookie-write origin check returns HTTP 403 with:

{"error":"Invalid request origin"}

Unexpected errors handled by the outer API error handler may return an error object without success. Do not require the tool envelope to recognize a failed request.

Rate limits and safe retries

Backing operations enforce their own limits; v1 does not publish a single global requests-per-minute allowance. Honor Retry-After when present and back off between read retries.

Creating a project or block is not replay-safe. After a timeout or server error, check whether it was created before trying again. Repeating an Arazzo workflow can create duplicates.