API and MCP errors
Most management errors return { "error": { "message": "..." } }. Some errors also include code, details or current_revision. Do not assume every response has a stable code: some provider/catalog errors use their own documented response shape.
| HTTP status | Meaning and next step |
|---|---|
| 400 | Invalid input. Correct the named field or JSON shape before trying again. |
| 401 | Missing, invalid, expired or revoked credentials. Check your workspace key. |
| 403 | The authenticated role cannot perform the action, or a browser Origin is not allowed for MCP. |
| 404 | The resource does not exist in this workspace. Another workspace's identifier does not grant access. |
| 409 | A state, revision or billing conflict. Inspect the returned code/details. |
| 429 | Invalid-credential throttling; wait for Retry-After. Provider limits may also apply. |
| 500 | Unexpected server error. The response hides private internal error details. |
| 503 | A required service or feature is disabled or unavailable. |
ASSISTANT_REVISION_CONFLICT is returned with HTTP 409 and current_revision when an assistant's If-Match revision is stale. Reload the assistant and review the changes before saving. Never remove the revision condition merely to overwrite a newer edit.
Billing errors carry codes such as billing_insufficient_balance and can have status 409 or a service-specific status. Follow the actual returned code and the workspace wallet/policy. APIFleet uses prepaid usage, not subscription_required or a free allowance.
MCP transport errors use HTTP status (401, 403, 405, 415 or unsupported-version 400). JSON-RPC envelope errors use error.code: -32600 for invalid requests, -32601 for unknown methods and -32602 for unknown tools/arguments. A native management failure returns result.isError: true, result.structuredContent.status with the REST status, and the native body in result.structuredContent.data. Read this even when HTTP is 200. The same body is encoded in result.content[0].text for clients without structured output support.
check_entitlements is a read: it may successfully return a wallet that needs funds, with a nested error.code of billing_insufficient_balance. It does not execute a paid action. Creating an assistant does not call anyone. An outbound-call timeout or simulation-start timeout does not prove that work was rejected. Reconcile the existing call/run before retrying; there is no universal Idempotency-Key guarantee for those actions.