Errors and limits

All non-2xx JSON errors use the same envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Request body must be an object."
  }
}

Branch on error.code, not error.message. The message is for developers and should not be shown directly to end users.

Error codes

HTTP	`error.code`	Caller action
400	`invalid_request`	Fix request shape, field value, body size, or unsupported field. Do not retry unchanged.
400	`invalid_json`	Fix serialization or `Content-Type`.
401	`unauthenticated`	Check `Authorization`; rotate or recreate the API token.
403	`forbidden`	Check that the API token can access this Agent, Thread, or file.
404	`not_found`	Check that the ID exists and is visible to this API token.
409	`agent_not_published`	Publish the Agent and enable API access.
409	`service_inactive`	Republish or repair the Agent in mosoo.
409	`readiness_blocked`	Fix Agent readiness or configuration in mosoo.
409	`idempotency_conflict`	Wait for `Retry-After` if in-flight, or use a new key when the body differs.
429	`rate_limited`	Back off and retry after `Retry-After`.
500	`internal_error`	Retry briefly with backoff; persist failure details if it repeats.

Idempotency-Key is supported on:

Rules:

For Project keys, the idempotency key is scoped to the Project, method, and route; the body is checked for conflicts. Keys in the same Project share receipts and rate limits, including after rotation. Account CLI credentials use their own credential boundary.
Reusing the same key with the same request replays the stored response.
Reusing the same key with a different request returns 409 idempotency_conflict.
Reusing the key while the first request is still processing returns 409 idempotency_conflict.
Keys must be non-empty and 128 characters or fewer.
Conflict responses can include Retry-After.

Generated endpoint-level request and response details.

API token and Agent access checks.