Unif API DocsErros
Todo erro que o UnifAPI retorna a agentes e clientes HTTP, o que ele significa e como se recuperar.
Os erros sempre voltam no mesmo envelope, independentemente de qual operação de dados públicos foi chamada:
{
"error": {
"type": "rate_limited",
"message": "Workspace rate limit exceeded.",
"request_id": "unif_5471f8cfa3814204a280b73df8c93167"
}
}error.typevem de um vocabulário fechado (veja a tabela abaixo) — estável, legível por máquina, seguro para que agentes e clientes façam switch.error.messageé para humanos e pode mudar sem aviso.error.request_idé o id de rastreamento do UnifAPI. Inclua-o nas solicitações de suporte.error.issuesestá presente apenas quandotype = validation_error— é a lista bruta de issues do Zod.
O status HTTP espelha o type — os clientes podem escolher o sinal que preferirem.
Referência
| Status | type | Quando acontece | Recuperação |
|---|---|---|---|
| 400 | validation_error | O request falhou na validação do gateway (query inválida, campo de body ausente). | Inspecione error.issues. Corrija o request. |
| 400 | invalid_id | O id fornecido era sintaticamente válido mas não foi aceito pela origem pública. | Use um id real. |
| 401 | unauthorized | As credenciais de OAuth ou de API key estão ausentes, malformadas, revogadas ou desativadas. | Reautentique ou faça a rotação da chave. |
| 404 | not_found | O recurso (vídeo, usuário, sala, ...) não existe, foi excluído ou é privado. | Confirme o id; alguns recursos são privados e retornam 404 por design. |
| 429 | rate_limited | Limite de taxa do workspace ou da origem excedido. | Respeite o Retry-After. Veja Limites de taxa. |
| 500 | internal_error | O próprio UnifAPI falhou (exceção não capturada). | Seguro para tentar novamente. Reporte o request_id se persistir. |
| 500 | response_shape_error | Os dados de origem não correspondem mais ao schema publicado. | Reporte o request_id — drift é um bug. |
| 502 | upstream_error | Uma origem de dados públicos retornou um erro do qual o UnifAPI não consegue se recuperar. | Inspecione o error.message. |
| 503 | upstream_unavailable | Uma origem de dados públicos atingiu timeout ou está inalcançável. | Tente novamente com backoff exponencial. |
A tabela acima é o contrato público para o vocabulário de erros atual.
Anatomia de um erro de validação
Para validation_error, o array issues carrega a lista bruta de issues do Zod para que um agente ou chamador possa mapear os erros de volta aos campos:
{
"error": {
"type": "validation_error",
"message": "Request validation failed.",
"issues": [
{
"code": "too_big",
"maximum": 50,
"type": "number",
"inclusive": true,
"path": ["limit"],
"message": "Number must be less than or equal to 50"
}
]
}
}Sempre registre o request_id
Toda resposta de erro carrega o request_id quando o UnifAPI consegue anexar um. Registre-o e inclua-o nas solicitações de suporte; é a forma mais rápida de depurar uma execução de Skill ou uma chamada HTTP que falhou.