Errors and fixes

When Echo's API cannot process a request, it returns an HTTP status (a 3-digit number that shows the result) and an error body in JSON.

Check these first

1. Base URL: https://token.echohub.io/v1 for the OpenAI format and https://token.echohub.io for the Anthropic format. If the path you call has no /v1, you get 404 even with a correct key (the response is the website's HTML page, not JSON)
2. API key: in 「APIキー」 (API keys) in the console, check that the key is not stopped and that it has spending limit left
3. Balance: check it in 「残高とチャージ」 (Balance and top-up) in the console
4. Model ID: check that it matches the ID in the model list

Error body format

Errors are returned in one of two formats, matching the format of the endpoint you called.

Example in the Anthropic format (wrong key):

{"type":"error","error":{"type":"authentication_error","message":"Invalid API key"}}

Example in the OpenAI format (insufficient balance):

{"error":{"message":"Insufficient balance","type":"api_error","param":"","code":"insufficient_quota"}}

• Decide the kind of error from the HTTP status and error.type (Anthropic format) or error.code (OpenAI format). The wording of message can change, so do not branch on it in your program
• For errors returned by the upstream API (the API of the provider that actually runs the model), message may contain the upstream's wording as is
• The order of the fields differs between errors

In the OpenAI format, error.type is mostly api_error for errors that Echo returns. When an upstream error is passed through as is, it holds the upstream's value. On the video generation endpoints (/v1/videos), error.type follows the HTTP status (invalid_request_error for 400, authentication_error for 401, permission_error for 403, not_found_error for 404 and 410, api_error for 500 and above).

Causes and fixes by case

Video generation errors

Errors specific to video generation (/v1/videos). The steps and the values each model accepts are in Video generation.

Errors returned at submission are free. A task whose generation failed shows status failed when you check its progress, and its price has been refunded in full.

Errors to retry

• Retry with a limit on the number of attempts, waiting a little longer each time
• If there is a Retry-After header, wait at least that many seconds. 429s caused by your account's rate limit and by the upstream API's rate limit carry Retry-After: 60, 429s caused by the per-IP limit carry the number of seconds to wait, and 503s carry Retry-After: 5 (a 503 caused by a problem with Echo's account at the upstream API can carry Retry-After: 60)
• A wrong model ID is also returned as 503. In the OpenAI format error.code is model_not_found. In the Anthropic format message contains does not exist or is not available
• The OpenAI and Anthropic SDKs retry 429 and 500-and-above errors up to 2 times by default, so a wrong model ID also fails only after 2 retries. Claude Code keeps retrying for more than a minute (Claude Code)

When streaming stops partway

With streaming (receiving the answer piece by piece), HTTP 200 is returned first and then the answer is sent. If the upstream API then returns an error or the connection is cut, you receive the following (as of 2026-09-27; planned fix: [ ]).

If the whole answer did not arrive, send the same request again. When the connection is cut, you are charged for what was generated before it was cut (Pricing and top-ups).

Contacting us

Every response that Echo's API processes, successful or not, has a request ID (a number that identifies one call). The same value is in the X-Request-Id and request-id response headers.

Contact us through https://echohub.io/contact with the following information. The contact form is on the Echo AI Hub site and can be used after the member site opens.

• When the error happened (Japan time)
• The request ID
• The model ID and the endpoint path you used
• The key's name (do not send the key itself)
• The HTTP status and the error body

Sources