Erros

As falhas compartilham um único envelope:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }],
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

code é estável e seguro para ramificações. message é para pessoas e pode mudar. details aparece quando conseguimos apontar o campo com problema.

Códigos

Código	Status	Significado	Repetir?
`MISSING_API_KEY`	401	Token bearer ausente ou incorreto.	Não: corrija a chave
`VALIDATION_ERROR`	400	Corpo malformado, `taskType` desconhecido ou ausência de `payload.prompt` e `payload.query`.	Não: corrija a requisição
`REGION_UNSUPPORTED`	422	Este mecanismo nunca pode atender o `country` solicitado.	Não: escolha outro mecanismo ou região
`REGION_UNAVAILABLE`	422	No momento não há capacidade para o `country` solicitado neste mecanismo.	Mais tarde, quando a capacidade voltar
`RESOURCE_ALREADY_EXISTS`	409	`idempotencyKey` duplicado no endpoint individual.	Não: a tarefa já existe
`PAYLOAD_TOO_LARGE`	413	O corpo do lote passa de 8 MB.	Não: envie partes menores
`RESOURCE_NOT_FOUND`	404	Id de tarefa desconhecido, ou a tarefa passou da janela pública de polling de 24 horas.	Não
`ENQUEUE_ERROR`	—	Falha de um item dentro de um lote (por exemplo, um soluço de banco de dados em uma faixa). Aparece em `results[].error`, nunca como status HTTP.	Sim

400 é para uma requisição que não conseguimos interpretar nem entender. 422 é reservado para uma requisição perfeitamente formada que não conseguimos atender na região solicitada. Ramificar por error.code é mais durável do que pelo status.

Recusas por região

Os dois códigos de região são decididos antes de a tarefa entrar na fila, então você fica sabendo na hora, em vez de ver uma tarefa gastar todas as tentativas e falhar com um erro que só mostra o sintoma. REGION_UNSUPPORTED é permanente: esse mecanismo não pode atender o país solicitado.

{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "CHATGPT cannot be served for country='CN': no proxy vendor has exit supply in CN. This is a permanent capability gap, not a transient one — retrying will not help. GOOGLE and AIMODE are unaffected by exit-IP limits and remain available for this country.",
    "details": { "taskType": "CHATGPT", "country": "CN", "cause": "no_proxy_route", "retryable": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}

Veja a tabela de combinações não atendidas. REGION_UNAVAILABLE é transitório: a rota existe, mas nada pode atendê-la neste momento. Consulte GET /capacity para ver o que cada região consegue atender agora.

Falhas de lote são por item

Um lote bem formado sempre retorna 200, mesmo que todas as tarefas dele falhem. O status HTTP descreve a requisição; results[].success descreve cada tarefa.

{
  "success": true,
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "success": true,  "index": 0, "task": { "...": "..." } },
    { "success": false, "index": 1, "error": { "code": "REGION_UNAVAILABLE", "message": "..." } },
    { "success": true,  "index": 2, "task": { "...": "..." } }
  ]
}

Só uma requisição malformada como um todo (não é JSON, não é array, vazia, mais de 500 itens, mais de 8 MB ou não autorizada) gera um 4xx para o próprio lote.

Um item do lote pode falhar com REGION_UNAVAILABLE ou ENQUEUE_ERROR, e nenhum dos dois consta no enum de erros por item do contrato de tarefas assíncronas que esta API implementa. Ambos são acréscimos, não substituições: VALIDATION_ERROR e RESOURCE_ALREADY_EXISTS não mudam.

Falhas no nível da tarefa

Uma tarefa que falha depois de entrar na fila não gera nenhum erro HTTP. Você descobre pelo status final:

{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}

Repare na diferença de formato: este error de nível superior é uma string, não o objeto {code, message, timestamp} dos erros de requisição. Ele começa com um código seguido de uma frase fixa para esse código, então decida pelo código: ENGINE_TIMEOUT, ENGINE_NO_RESULT, ENGINE_FAILED, ou NO_IP_AVAILABLE e NO_ACCOUNT_AVAILABLE quando nenhuma capacidade ficou livre a tempo (tentar de novo mais tarde costuma funcionar). BAD_PAYLOAD e PAGE_UNAVAILABLE (uma página do Naver que não pode ser lida de forma anônima) mantêm uma mensagem que diz o que mudar. A mesma tarefa entrega um webhook com task.status === "FAILED".

Primeiros passos

Conceitos principais

Mecanismos

Source Influence

Prompt Research

Monitoramento GEO

Migração

Códigos

Recusas por região

Falhas de lote são por item

Falhas no nível da tarefa

​Códigos

​Recusas por região

​Falhas de lote são por item

​Falhas no nível da tarefa

Códigos

Recusas por região

Falhas de lote são por item

Falhas no nível da tarefa