Errors

The API fails closed and predictable: auth and credit checks run before any workflow executes, and you are never billed for a failed call.

HTTP status codes (REST)

Status	Meaning	What to do
401	Missing, revoked or invalid X-Api-Token	Copy the active key from the Studio APIs tab
403	Key's organization has no World Cup entitlement	Claim a tier at machina.gg/world-cup-api
402	Insufficient credits for this endpoint's cost	Top up under the APIs tab — the call was not executed
404	Endpoint's workflow not available	Transient during maintenance; retry later
429	Rate limited	Honor Retry-After (seconds) and retry
502	The underlying workflow reported a failure	Safe to retry once — not billed

Error body shape:

{
  "data": {},
  "error": { "code": 402, "message": "Insufficient credits for this endpoint" },
  "meta": { "code": 402 },
  "status": "error"
}

Typed errors (MCP)

MCP tools return a structured error object designed for agents to act on without parsing prose:

{
  "status": "error",
  "error": {
    "type": "insufficient_credits",
    "http_status": 402,
    "hint": "The organization is out of prepaid credits — top up in Studio under the APIs tab.",
    "detail": { "...": "raw gateway response" }
  }
}

error.type	HTTP	Notes
invalid_api_key	401	key missing/revoked/wrong
not_entitled	403	org doesn't hold the product
insufficient_credits	402	top up, then retry
not_available	404	endpoint workflow offline
rate_limited	429	includes retry_after_seconds
upstream_error	5xx	safe to retry once

Billing guarantees

• 402 happens before execution — a blocked call never runs and never charges.
• 5xx never bills — the debit is written only after a genuinely successful execution.
• health is free precisely so you (or your agent) can verify a key without spending.