Error Codes and Troubleshooting

When troubleshooting, first record: the HTTP status code, the request identifier returned by the platform, the model ID, task ID, asset ID, and the original error code.

Do not record the API key, portrait session token, or full asset download URLs; redact them before submitting to platform support.

HTTP status meanings

404 has three causes; don't always assume "the ID is wrong"

This is the most commonly misjudged point during troubleshooting:

When you get a 404, first confirm whether the path and method match, then suspect the ID.

A missing video task returns 400, not 404

This is inconsistent with other APIs and requires special attention:

Video task queries return 400 with a top-level {code, message, data} structure, which is neither 404 nor the error object structure described below.

Error responses have three structures

1. Model / image / video generation APIs — error object

On failure, the API returns a non-2xx HTTP status with an error object:

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

code may be an empty string. Observed: code is "" both for authentication failures and for request bodies whose JSON cannot be parsed. Do not use whether code is empty to decide "whether this is an error"; rely on the HTTP status code and read message first.

type is not a stable classification field. When you need to classify errors, read code and do not rely on the value of type.

2. Asset library APIs — top-level code

Returns a non-2xx HTTP status, with code matching the HTTP status:

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

3. Video task queries — top-level code string

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

Note that code here is the string task_not_exist, not a number.

request id: the key identifier for troubleshooting

The platform writes the request id directly into error.message; you do not need to look for it in the headers:

"message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)"

Extract it with a single command:

curl -s "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer sk-invalid" \
  | grep -oE 'request id: [A-Za-z0-9]+'

Including this request id when filing a ticket can significantly shorten the time needed to locate the issue.

Authentication failures

When the API key is missing, incorrect, or expired, all APIs return HTTP 401 and:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}

Note that code is an empty string — this is exactly why we warned above not to rely on code.

Model and generation errors

Asset library errors

An asset still under review is not an error: the query returns 200 with status of Processing; keep polling the same asset ID.

Empty output from a reasoning model is also not an HTTP error: if the response is 200, finish_reason is length, and usage.completion_tokens_details.reasoning_tokens has used up the output limit, increase the output quota or switch to a non-reasoning model.

Portrait authorization errors

Rate limiting and retries

• 429 means requests are too frequent; back off and retry as instructed, and do not retry concurrently;
• For asset status, query every 5–10 seconds; for video tasks, every 5–15 seconds;
• Retry only on 429 and brief 5xx; for 400 / 401 / 403 / 404, fix the request directly;
• Before retrying, query by task ID / asset ID to avoid duplicate creation and duplicate charges.

Quick self-check

1. Is Authorization set to Bearer <API Key>, and is the key still enabled;
2. Is the request domain the address currently specified in the console (default https://locopalai.com; overseas models may use https://us-api.locopalai.com);
3. Does model come from data[].id in /v1/models;
4. Is the asset status already Active;
5. Is the reference image / video URL a publicly accessible http(s) address that does not depend on cookies or Referer;
6. Has the same task / asset been submitted more than once.

What to include when contacting support

• Request time and API path;
• HTTP status code and the full response body (with the API key redacted);
• The request identifier, task ID, or asset ID returned by the platform;
• The model ID and parameters involved;
• A minimal reproducible request example.