O envelope único de falha e a tabela de códigos retornados pela API.
Toda falha da API responde com o mesmo envelope, em qualquer status.
{
"error": {
"category": "NotFoundException",
"code": "ERR_SCAN_NOT_FOUND",
"statusCode": 404,
"message": "The scan ID 'abc' was not found.",
"traceId": "3f1c9a2e-7b40-4d18-9c55-1e0a6f2b8d31",
"timestamp": 1756300000000,
"details": [{ "field": "page", "message": "Expected number" }]
}
}| Campo | Descrição |
|---|---|
category | Família da exceção que originou a resposta |
code | Código estável do erro |
statusCode | Status HTTP, repetido no corpo |
message | Descrição legível |
traceId | Identificador da requisição, para acionar o suporte |
timestamp | Epoch em milissegundos no momento da resposta |
details | Erros por campo; presente apenas em falha de validação, com o nome do parâmetro ou campo rejeitado |
traceId repete o valor do header de resposta x-request-id. Guarde-o no seu log: é o que a equipe técnica da Pixlog usa para localizar a requisição exata.
Códigos
| Status | Código | Quando ocorre |
|---|---|---|
400 | ERR_BAD_REQUEST | O corpo da requisição não é um JSON válido |
401 | ERR_MISSING_TOKEN | A requisição não inclui o header Authorization |
401 | ERR_INVALID_API_TOKEN | O token é malformado, inexistente ou tem segredo incorreto |
401 | ERR_API_TOKEN_REVOKED | O token foi revogado |
401 | ERR_API_TOKEN_EXPIRED | O token venceu |
403 | ERR_INSUFFICIENT_SCOPE | O token é válido, mas não tem a permissão exigida pela rota |
403 | ERR_API_TOKEN_NOT_ALLOWED | A rota não aceita token de aplicação |
403 | ERR_SCAN_NOT_OWNED | O escaneamento pertence a outra organização |
403 | ERR_MERGED_NOT_OWNED | O grupo pertence a outra organização |
404 | ERR_USER_NOT_FOUND | O usuário não existe ou está fora da organização do token |
404 | ERR_SCAN_NOT_FOUND | O escaneamento não existe ou está fora do alcance do token |
404 | ERR_MERGED_NOT_FOUND | O grupo não existe ou está fora do alcance do token |
422 | DTO_VALIDATION | A query ou o corpo é inválido; details identifica cada campo |
429 | ERR_RATE_LIMIT_EXCEEDED | O limite de uso foi excedido; veja Autenticação |
500 | ERR_UNKNOWN | Ocorreu uma falha inesperada no servidor |