Errors and status codes

Interpret API problem responses, recover failed requests, and distinguish HTTP failures from failed translation work.

Check the HTTP status before decoding a successful response. The API at https://api.lingo.dev/v2 reports failures as JSON problem details. A successfully retrieved job can still describe failed work, so inspect its status as well.

Read a problem response #

Problem responses use Content-Type: application/problem+json. Common fields are type, title, status, and detail; named problems also contain fields identifying the affected resource or repair.

This example is a missing localization job:

json
{
  "type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
  "title": "Localization job not found",
  "status": 404,
  "detail": "Localization job lfr_example not found.",
  "id": "lfr_example"
}

The type URI identifies the problem. Use the API error catalogue for each named problem's fields and endpoints. Keep the returned URI unchanged when storing or classifying an error.

Correct an invalid request #

A request that fails validation returns 400 Bad Request with type: "about:blank". When validation details are available, errors lists each issue's path and message:

json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "path": ["payload", "documents", 0, "source"],
      "message": "Expected a JSON object"
    }
  ]
}

The path begins with the part of the request being validated, such as payload, followed by property names and zero-based array indexes. This example identifies source in the first documents entry in the request body. Correct the indicated value against the endpoint's schema before submitting again. about:blank is a generic problem type, so it has no entry in the named error catalogue.

Choose the recovery #

HTTP statusTypical causeNext action
400A request does not match the route's schema.Correct the path, query, headers, or body using the reported validation details.
401Missing, invalid, or expired credentials.Load the intended key or renew the user session.
402Insufficient credits, unavailable plan features, or a service key disabled after an RBAC downgrade.Read the named condition and resolve the account or plan requirement.
403Missing permission, a required user identity, or a feature-flag restriction.Check the caller and the operation’s access requirements.
404The resource does not exist or is not visible to this caller.Check the identifier, organization, and resource permissions.
409The operation conflicts with the resource's state.Read the current resource. Upload missing artifacts, finish running work, or refresh a closed review as indicated.
413An upload or request body exceeds the size limit.Reduce the input or split the work; artifact uploads allow up to 25 MiB each.
422The request is structurally valid but violates an operation's constraints.Correct the named condition, such as an invalid review edit or reused idempotency key.
429A usage or operation limit was reached.Follow the problem's retry time when supplied; otherwise check the account limit before retrying.
5xxA server or dependency could not complete the request.Retain the resource and request IDs; retry only according to the operation's semantics.

detail explains the particular failure; the status alone is not a complete classification. Responses from a proxy or network failure may not contain a problem body. Preserve their HTTP status and readable response text for diagnosis without logging secrets.

Retry a localization submission #

Save the create request's Idempotency-Key before sending it. If its response is lost, repeat the same create request with that key to retrieve the original job. A new key creates new work.

After creation, save the job ID. Read that job before deciding to create another. Uploads use the exact bytes named by their SHA-256 address; complete missing uploads before starting. Repeating /start works on the same job.

Admission checks happen at start. DailyTokenLimitReached or insufficient credits leaves a pending job available to start later once the account condition is resolved. Repeatedly creating new jobs does not repair an account limit.

Distinguish request failure from work failure #

An HTTP 200 from GET /v2/localization/jobs/:id means the job was retrieved. Its status._tag can still be Failed. Read status.message, each target's status, and stage warnings and failures.

Completed targets remain downloadable even if another target fails. Keep them and submit only the work that needs regeneration after correcting the cause. A client polling timeout does not cancel the job.

Provisioning has its own per-kind results and recovery. Review decisions have their own closed-review and invalid-edit errors. Use those resources' state when recovering instead of treating every failure as a reason to repeat the original write.