Operate
Error handling
Recover from authentication, billing, connector, and MCP failures returned by the CoreSpeed production surface.
HTTP failures use a nested error envelope:
{
"error": {
"type": "authentication_error",
"message": "Authorization header or x-api-key is required",
"code": "missing_authorization"
}
}| Status | Code | Recovery |
|---|---|---|
| 401 | missing_authorization | Add an Authorization or x-api-key header. |
| 401 | invalid_jwt | Refresh the WorkOS session and retry with the new JWT. |
| 401 | invalid_api_key | Replace a revoked, expired, or unknown key. |
| 402 | payment_required | Add organization balance in the dashboard. |
| 402 | key_spend_limit_exceeded | Raise the API-key monthly cap or wait for reset. |
| 403 | org_suspended | Contact support; top-up does not clear an administrative suspension. |
| 404 | endpoint_not_found | Stop using a retired per-connector or per-engine MCP URL; call /mcp. |
| 500 | internal_error | Retry with backoff and retain the request ID for support. |
MCP tool errors
An MCP transport can return HTTP 200 while the JSON-RPC tool result contains
isError: true. Check both layers before treating a call as successful.
Expected tool-level failures include:
- a connector account that moved to
needs_reauth; - an organization hold, suspension, or API-key spend cap caught before a metered tool executes;
- an upstream connector API rejecting the requested operation;
- a capability that is no longer present in the caller's
tools/listresult.
For needs_reauth, send the user back to Dashboard → Connectors. Do not rotate
the CoreSpeed key: the problem belongs to the upstream OAuth grant.
Earlier releases used insufficient_balance and wallet_blocked. Current
clients should branch on payment_required and org_suspended instead.