Skip to main content

Errors

Every API error is an HTTP status code plus a JSON body describing the cause.

Response shape​

{ "error": "short_code", "message": "human-readable explanation" }

Some endpoints return just { "error": "message" } without a short code — depends on the origin (proxy vs. handler).

Status code reference​

400 Bad Request​

Malformed input — missing required field, wrong type, invalid enum value.

Fix: read the message, correct the request body / query string.

401 Unauthorized​

No API key, malformed API key, or revoked API key.

Fix: verify the Authorization: Bearer eco_... header. If it's definitely set, check the API Keys page in the console — the key may have been revoked. Create a new one.

402 Payment Required​

Two sub-cases based on the error code:

  • insufficient_balance — account balance can't cover the request.
  • model_not_priced — the model ID exists but no pricing has been set yet. Ping #ecolink-support.

Fix: top up the balance (for insufficient_balance) or reach out via Slack (for model_not_priced).

403 Forbidden​

Authenticated but trying to access something you don't own — another account's inference instance, a resource your role doesn't permit.

Fix: confirm you're acting on the right account (account switcher in the console). If you believe you SHOULD have access, check with an Owner on the account.

404 Not Found​

  • Unknown model ID — typo, or model was deprecated
  • Unknown resource ID — instance / cluster / drive was deleted

Fix: check spelling; verify the resource exists in the console.

409 Conflict​

Resource constraint violation — e.g., trying to launch an instance with a name that's already in use, or creating a drive that would exceed per-account limits.

Fix: read the message for the specific constraint.

429 Too Many Requests​

Rate limit hit. See Rate limits.

Fix: back off and retry with exponential delay.

500 Internal Server Error​

Something went wrong server-side. Usually transient.

Fix: retry. If persistent, include the x-ecolink-request-id response header when asking in #ecolink-support.

502 Bad Gateway / 503 Service Unavailable​

A backend the API was forwarding to is unhealthy. For inference, this usually means the target model has no healthy pod right now — rare, typically resolves in seconds.

Fix: retry after a few seconds. If it persists for more than a minute on a single model, report it in #ecolink-support.

504 Gateway Timeout​

The upstream took too long. Can happen on large video generations or very long chat completions pushing hard timeouts.

Fix: retry with smaller parameters (shorter max_tokens, fewer num_frames), or use streaming for chat.

Helpful response headers​

HeaderWhat it tells you
x-ecolink-regionWhich region served the request (mv / tn / hk etc.)
x-ecolink-request-idUnique request ID — include in bug reports

General debugging pattern​

  1. Capture the full error response (status + body + headers).
  2. Check the console's Messages page — some 402s / 429s have a matching notification with more context.
  3. Try the same request in the Playground — if the Playground call works, the issue is in your client code; if it fails the same way, it's a platform / balance / model issue.
  4. Escalate in #ecolink-support with the x-ecolink-request-id.