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: An upstream service or the gateway cannot complete the request temporarily.
  • 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.

Diagnosing video failures​

First locate the failure: before submission, PopGo parsing, service acceptance, polling or download. Keep the specific error phrase;500 or missing service logs alone cannot locate the cause.

StageAction
first-frame requires exactly one / first-last-frame requires bothChoose the mode, provide one first frame or two distinct slots, and inspect input edges and actual counts
reference-audio requires at least one / audio not supportedConfirm audio capability and attachment permission for this mode; supply audio; generate_audio does not grant reference permission
unsupported protocol: data / invalid sourceUse a permitted public URL for URL-only models; the Local badge does not publish a file
Long0% / completed with failed downloadQuery the original id and allow content preparation; do not recreate to avoid waiting
Successful generation ignores mediaInspect fields and accessibility, then the output;HTTP200 is insufficient

HTTP400 generally requires a corrected request;500 may originate in parsing or an intermediate layer;503 often indicates temporary capacity. Inspect sanitized details first. Video task diagnostics covers polling,costs and evidence boundaries.