Códigos de erro e diagnóstico

Estrutura padrão de erros HTTP, catálogo de códigos e resiliência.

Quando uma chamada não pode ser processada, o SmallPict retorna um código HTTP padrão com um objeto JSON estruturado para facilitar o diagnóstico rápido.

Estrutura de erro JSON

JSON

{  "success": false,  "error": {    "code": "INVALID_IMAGE_PAYLOAD",    "message": "O arquivo enviado não é uma imagem válida ou está corrompido.",    "details": {      "mime_type": "text/html",      "expected": [        "image/jpeg",        "image/png",        "image/webp",        "image/avif"      ]    }  }}

Catálogo de erros HTTP

Código	Identificador	Causa	Solução
`400`	`BAD_REQUEST`	Payload JSON malformado ou parâmetros inválidos.	Corrija a sintaxe JSON e os nomes de campos.
`401`	`UNAUTHORIZED`	Chave de API ausente ou inválida.	Verifique se o cabeçalho `X-API-Key` está correto.
`401`	`TIMESTAMP_DRIFT`	Desvio de relógio superior a ±300 segundos.	Sincronize o relógio do seu servidor com um servidor NTP.
`401`	`INVALID_SIGNATURE`	Assinatura HMAC-SHA256 incorreta.	Revise o cálculo da cadeia canônica e a secret key.
`403`	`FORBIDDEN`	Permissão insuficiente para o recurso.	Verifique os escopos da chave no painel.
`404`	`NOT_FOUND`	Tarefa (`job_id`) ou recurso inexistente.	Valide o identificador fornecido na URL.
`413`	`PAYLOAD_TOO_LARGE`	Arquivo excede o tamanho máximo permitido pelo seu plano.	Diminua a resolução ou compacte o arquivo antes.
`415`	`UNSUPPORTED_MEDIA`	Formato de mídia não suportado.	Utilize JPEG, PNG, WebP, AVIF ou SVG.
`422`	`UNPROCESSABLE`	Arquivo com cabeçalho válido mas corrompido.	Certifique-se de que o upload não foi truncado.
`429`	`RATE_LIMIT_EXCEEDED`	Limite de requisições por segundo excedido.	Implemente repetições com Exponential Backoff.
`429`	`QUOTA_EXCEEDED`	Cota mensal de transformações esgotada.	Faça upgrade do seu plano no painel.
`500`	`INTERNAL_ERROR`	Falha interna transitória no cluster.	Tente novamente após breve intervalo.
`503`	`SERVICE_UNAVAILABLE`	Manutenção programada ou sobrecarga temporária.	Reenvie a requisição em modo de fallback.