Error codes

All error responses use a consistent JSON envelope:

{"error": "Human-readable description", "code": "MACHINE_READABLE_CODE"}

Use the code field for programmatic handling - the error string may change without notice. The code field is stable across API versions.

Full code table

The HTTP column is the status you get on /v1/. On /mcp it does not apply: every error there is an HTTP 200 carrying a JSON-RPC error member, including the authentication, entitlement and rate-limit refusals decided before your tool runs. See MCP JSON-RPC error mappings for the translation.

Maintenance windows

MAINTENANCE_MODE is the one refusal that is deliberate rather than a fault, so it is worth handling apart from SERVICE_UNAVAILABLE. Its REST 503 and its MCP reply (which is an HTTP 200, see below) both carry two headers:

• Retry-After - seconds until the window's declared end, or 300 when there is no declared end (and also when the declared end has passed while the window is still open).
• X-Maintenance-Mode: 1

The REST body carries one key beyond the usual envelope:

{
  "error": "Service is under maintenance",
  "code": "MAINTENANCE_MODE",
  "maintenance": {
    "message": "Scheduled database upgrade",
    "ends_at": "2026-08-07T03:00:00+00:00"
  }
}

maintenance.message is the operator's note and maintenance.ends_at is the declared end; either can be null. Neither is a commitment - treat Retry-After as the value to back off on.

Health and reference endpoints keep serving during a window, so /health and /openapi.json are not a way to detect one. The 503 itself is the signal.

MCP JSON-RPC error mappings

When accessed via MCP (POST /mcp), HTTP errors are translated to JSON-RPC error codes:

Every MCP error is an HTTP 200 carrying a JSON-RPC error member. That includes every condition REST answers with a status code an HTTP client would normally branch on: an authentication failure, an entitlement refusal, a rate-limit breach and a maintenance window are all decided before the tool runs, and all four still arrive as JSON-RPC. Branch on the JSON-RPC error.code, or on data.code, rather than on the transport status - on /mcp there is no status to branch on.

The data field of every MCP error contains the original {"code": "...", "error": "..."} envelope. Two codes add keys to it so an agent can back off for the right length of time without parsing headers:

• -32003 adds retry_after_seconds. The Retry-After header carries the same value, for non-agent clients.
• -32006 adds reason, ends_at and retry_after_seconds.
• -32004 adds check_frequency, cap, held, resets_at and reason when the code is INSUFFICIENT_CREDITS or PROMPT_LIMIT_REACHED and the REST body carries them. The other -32004 codes carry no extra keys.

-32004 groups every refusal the workspace clears by paying: the add-on switched off, a payment not confirmed, a read-only subscription (SUBSCRIPTION_READ_ONLY, a 403 on /v1/) and a plan cap (the four cap codes, each a 402 on /v1/).

A code with no row in the table above follows the HTTP status it carries on /v1/: 400 and 422 arrive as -32602, 401 as -32001, 402 as -32004, 403 as -32002, 404 as -32005, 409 as -32009, 429 as -32003, and any other status as -32000 ServerError. data.code always carries the REST code, so branch on it rather than on the JSON-RPC code before retrying, since a plain retry will not clear a -32009 or a -32004.

TOKEN_LIMIT_REACHED is listed for completeness. It is answered when a token is created in the app, which no MCP tool does.

Getting help

status.ziptie.ai carries incident notices. It is maintained by hand, so the absence of a notice is not an automated all-clear. It is hosted off the platform it reports on, so it stays reachable through an outage large enough to take everything else down. The Terms of Service carry no contractual uptime commitment, so a 500 or 503 that survives a retry is worth reporting rather than waiting out, whatever the page says.

Responses from api.ziptie.ai carry an X-Request-ID header. Include it, the UTC timestamp, the endpoint and the code you received, then use either:

• The in-app Support Center at https://app.ziptie.ai/w/<workspace_id>/support - open a thread there and it arrives already tied to your workspace and subscription.
• Email [email protected].

Neither channel publishes a response-time target, and there is no separate incident hotline.

A suspected security vulnerability goes to [email protected] instead, acknowledged within 5 business days. That address is also published at /.well-known/security.txt. Do not open a support thread for one: it queues behind billing questions and is read by the wrong person first.