Skip to main content

Error Fixes

Use the symptom and HTTP status to find the cause, verify the smallest fix, then restore the request step by step.

401 Unauthorized​

  • Symptom: The request usually returns 401 Unauthorized; a client may show only “request failed”.
  • Cause: The Key is missing, inactive, incomplete, or sent with the wrong authentication header.
  • Checks:
    1. Record the full HTTP status, path, and timestamp.
    2. Copy the Key again and check whitespace, expiry, and whether it is active.
    3. Compare the Base URL, model, and authentication header with the protocol guide, then verify with minimal curl.
  • Fix: Copy the Key again, remove surrounding whitespace, and verify Bearer, x-api-key, or x-goog-api-key for the selected protocol.
  • Verify: After the fix, send one short text request first. Restore the original parameters only after normal JSON content returns.

403 Forbidden​

  • Symptom: The request usually returns 403 Forbidden; a client may show only “request failed”.
  • Cause: The current Key, account state, or model access does not permit the request.
  • Checks:
    1. Record the full HTTP status, path, and timestamp.
    2. Copy the Key again and check whitespace, expiry, and whether it is active.
    3. Compare the Base URL, model, and authentication header with the protocol guide, then verify with minimal curl.
  • Fix: Confirm that the Key is active and choose a currently accessible model on the models and pricing page.
  • Verify: After the fix, send one short text request first. Restore the original parameters only after normal JSON content returns.

404 Not found​

  • Symptom: The request usually returns 404 Not found; a client may show only “request failed”.
  • Cause: The Base URL, protocol path, or HTTP method does not match; the client may also append /v1 twice.
  • Checks:
    1. Record the full HTTP status, path, and timestamp.
    2. Copy the Key again and check whitespace, expiry, and whether it is active.
    3. Compare the Base URL, model, and authentication header with the protocol guide, then verify with minimal curl.
  • Fix: Compare the full method and path with the protocol guide and enter only the documented Base URL level.
  • Verify: After the fix, send one short text request first. Restore the original parameters only after normal JSON content returns.

429 Too many requests​

  • Symptom: The request usually returns 429 Too many requests; a client may show only “request failed”.
  • Cause: Requests are arriving too quickly, or the currently available balance is insufficient.
  • Checks:
    1. Record the full HTTP status, path, and timestamp.
    2. Copy the Key again and check whitespace, expiry, and whether it is active.
    3. Compare the Base URL, model, and authentication header with the protocol guide, then verify with minimal curl.
  • Fix: Reduce concurrency, retry with increasing delays, and confirm account state in the portal before continuing.
  • Verify: After the fix, send one short text request first. Restore the original parameters only after normal JSON content returns.

5xx Service error​

  • Symptom: The request usually returns 5xx Service error; a client may show only “request failed”.
  • Cause: The service is temporarily unable to complete the request.
  • Checks:
    1. Record the full HTTP status, path, and timestamp.
    2. Copy the Key again and check whitespace, expiry, and whether it is active.
    3. Compare the Base URL, model, and authentication header with the protocol guide, then verify with minimal curl.
  • Fix: Keep the timestamp and status, then retry later. If it continues, run the minimal curl request to isolate client configuration.
  • Verify: After the fix, send one short text request first. Restore the original parameters only after normal JSON content returns.

Network interruption​

  • Symptom: The request usually returns Network interruption; a client may show only “request failed”.
  • Cause: A local network, proxy, or long-lived connection closed before the response completed.
  • Checks:
    1. Record the full HTTP status, path, and timestamp.
    2. Copy the Key again and check whitespace, expiry, and whether it is active.
    3. Compare the Base URL, model, and authentication header with the protocol guide, then verify with minimal curl.
  • Fix: Confirm the domain is reachable. Reconnect streams with backoff and do not automatically repeat non-idempotent operations.
  • Verify: After the fix, send one short text request first. Restore the original parameters only after normal JSON content returns.
  1. Record the full error first: HTTP status, request path, client, and timestamp.
  2. Reproduce it with the minimal curl request from Quickstart to separate the Key, model, URL, and client.
  3. Change one variable at a time. Verify a short text request before restoring streaming, tools, or media parameters.

If the issue continues​

Keep the timestamp, protocol, HTTP method, path, status, and a redacted response excerpt. Never include the full Key.

Video troubleshooting

Record the HTTP status, error code, and a short message, then use the table below. See video model parameters for fields and limits and the task workflow for the call sequence.

SymptomCheck and action
HTTP 400 / invalid parametersCheck required fields, types, duration, resolution, aspect ratio, reference counts, and roles for the model. Correct the request before submitting again.
HTTP 401 / 403Check Authorization: Bearer YOUR_API_KEY, Key status, model permissions, and balance. Do not put the Key in URL parameters.
HTTP 404Check the method and full path; do not append /v1 twice. Use the returned task ID and a Key with access to it for queries and downloads.
HTTP 429Reduce concurrency, honor Retry-After, use bounded backoff, and check balance. If the creation result is unclear, follow the timeout guidance below.
HTTP 502 / 503 or network errorsRetry queries and downloads for the same task a limited number of times. If the creation result is unclear, follow the timeout guidance below to avoid creating twice.
Media fetch failure / 403 / expired linkUse a directly downloadable public HTTPS link valid until generation finishes. Check public access, actual format, size and duration. Browser preview does not guarantee server download access.
Persistent queued / in_progress or progress at 0Keep the ID, allow a longer client wait, and continue bounded polling. Progress may be absent or update only at completion. Do not create again.
completed but download failsCheck the same task’s /content response, HTTP status, and Content-Type. Retry temporarily unavailable content a limited number of times and save promptly. Do not save a JSON error as MP4.
Reference effect differsCheck the actual fields, count, order, and roles sent. Ordinary references differ from first and last frames. Compare the downloaded result before creating again.

Creation timeouts and duplicates​

If you received an id, keep querying that task. If you did not receive an id, do not retry yet; save the X-Oneapi-Request-Id response header if received, the request time, and the model name, then contact support. You currently cannot retrieve a task yourself using a request ID. Creating again can incur another charge; sending idempotency_key does not guarantee deduplication.

What to provide to support​

Provide the model, time and time zone, HTTP status, error code, request format, nonsensitive parameters, and reference types and counts. Share task or request IDs privately with support. Public examples should use YOUR_TASK_ID and YOUR_IMAGE_URL placeholders. Remove API Keys, Authorization headers, cookies, signed links, and private media. Check usage and bills for charges after errors or timeouts.