Códigos de error y solución de problemas

Estructura estándar de errores HTTP, códigos de diagnóstico y estrategias de resiliencia.

Cuando una solicitud a la API no puede completarse con éxito, SmallPict devuelve un código de estado HTTP estándar acompañado de un objeto JSON estructurado con información detallada para facilitar la depuración.

Envoltorio de error estándar

JSON

{  "success": false,  "error": {    "code": "INVALID_IMAGE_PAYLOAD",    "message": "El archivo proporcionado no es una imagen válida o está dañado.",    "details": {      "mime_type": "text/html",      "expected": [        "image/jpeg",        "image/png",        "image/webp",        "image/avif"      ]    }  }}

Catálogo de códigos de error HTTP

Código	Identificador	Causa principal	Solución recomendada
`400`	`BAD_REQUEST`	Cuerpo JSON con formato inválido o parámetros incorrectos.	Valida la sintaxis del JSON y los nombres de las propiedades.
`401`	`UNAUTHORIZED`	Clave de API ausente, inválida o revocada.	Verifica que la cabecera `X-API-Key` contenga una clave activa.
`401`	`TIMESTAMP_DRIFT`	Desviación de reloj superior a ±300 segundos.	Sincroniza la hora de tu servidor con un servidor NTP oficial.
`401`	`INVALID_SIGNATURE`	La firma HMAC-SHA256 calculada no coincide.	Revisa el cálculo de la cadena canónica y la clave secreta.
`403`	`FORBIDDEN`	La clave no tiene permisos para el recurso solicitado.	Revisa los alcances asignados a tu clave en el panel.
`404`	`NOT_FOUND`	La tarea (`job_id`) o recurso solicitado no existe.	Verifica el identificador pasado en la URL del endpoint.
`413`	`PAYLOAD_TOO_LARGE`	El archivo supera el tamaño máximo permitido por tu plan.	Reduce el tamaño del archivo o comprímelo previamente.
`415`	`UNSUPPORTED_MEDIA`	Tipo de archivo no compatible con el motor de conversión.	Envía únicamente archivos JPEG, PNG, WebP, AVIF o SVG.
`422`	`UNPROCESSABLE`	El archivo tiene una extensión válida pero está corrupto.	Comprueba que el archivo no esté truncado en origen.
`429`	`RATE_LIMIT_EXCEEDED`	Has superado el límite de solicitudes por segundo permitido.	Implementa reintentos con algoritmo Exponential Backoff.
`429`	`QUOTA_EXCEEDED`	Se ha consumido el 100% de la cuota mensual contratada.	Actualiza tu plan en el panel de control.
`500`	`INTERNAL_ERROR`	Error inesperado en los servidores de procesamiento.	Reintenta la solicitud tras un breve intervalo de espera.
`503`	`SERVICE_UNAVAILABLE`	Mantenimiento programado o sobrecarga temporal.	Reintenta con respaldo en el modo passthrough.