Skip to main content

Errors

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

Response shape​

{ "error": "human-readable explanation" }

error is written for people. It is reworded whenever wording can be clearer, so treat it as display text rather than something to match on.

Endpoints that publish a stable error enum add a code alongside it:

{
  "error": "A reference audio or video clip is too long — each must be 15 seconds or shorter. Please trim it and try again.",
  "code": "reference_media_too_long"
}

code is the value to branch on. It is stable, and new values are only ever added — never renamed. Where an endpoint has no enum yet the field is absent, so check for it rather than assuming it is there.

Enums published today:

Whatever the endpoint, the HTTP status is always meaningful — the table below applies everywhere.

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​

Three sub-cases, told apart by the error text:

  • insufficient credits — the account balance can't cover the request.
  • service paused: invoice past due — a monthly invoice is unpaid. Applies to post-paid accounts.
  • model_not_priced: ... — the model ID exists but no pricing has been set for it yet.

Fix: top up the balance, pay the open invoice at /billing/invoices, or contact support for an unpriced model.

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 it persists, report it with the details listed under Reporting a failure.

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.

General debugging pattern​

  1. Capture the full error response — status code and body.
  2. Check the console's Messages page — some 402s and 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 or model issue.
  4. Still stuck — report it.

Reporting a failure​

Include:

  • The HTTP status and the full response body, including code if present.
  • The model ID and roughly when the call was made, with a timezone.
  • For an asynchronous job, its id — that identifies the exact run.
  • Whether it reproduces, or happened once.

The job id is the single most useful item for anything that got as far as being accepted, since it ties directly to that run.