Errores
La API de atoship usa los códigos de respuesta HTTP convencionales para indicar si una solicitud fue exitosa o falló. Los códigos del rango 2xx indican éxito, los 4xx indican errores del cliente y los 5xx indican errores del servidor.
Códigos de estado HTTP
Códigos de éxito
La solicitud se completó correctamente
El recurso se creó correctamente
Errores del cliente
Parámetros de la solicitud no válidos
Clave de API no válida o ausente
Saldo insuficiente o pago rechazado
La clave de API no tiene los permisos necesarios
El recurso no existe
Error de validación en los datos de la solicitud
Se superó el límite de velocidad
Errores del servidor
Algo salió mal de nuestro lado
La API no está disponible temporalmente
Objeto de error
Cada error devuelve un JSON con un objeto error. Ramifica según el código de estado HTTP y error.code: ambos están en toda respuesta de error.
error.codestringCódigo legible por máquina en MAYÚSCULAS_CON_GUION_BAJO (p. ej. "RATE_LIMIT_EXCEEDED"). Este es el campo por el que ramificar.
error.messagestringDescripción legible por personas. Puedes mostrarla al usuario; no la parsees, la redacción cambia.
error.detailsarray (opcional)Salida del validador en un 400. Cada entrada trae path y message; la forma depende del campo que falló.
error.paramstring (opcional)El campo culpable, cuando puede nombrarse uno solo (p. ej. "to_address.phone").
error.retryAfternumber (opcional)Segundos de espera, solo en un 429. El mismo valor va en la cabecera Retry-After.
Las respuestas también llevan object, y algunas mode. Ninguno está garantizado en todos los endpoints, así que no ramifiques por ellos. No existe un campo type ni request_id.
Manejo de errores
Usa el código de estado para determinar la categoría del error
El código en MAYÚSCULAS_CON_GUION_BAJO es el identificador estable: compara contra él, no contra el texto del mensaje
Muestra el message a los usuarios para darles información útil
Espera error.retryAfter segundos (o lee la cabecera Retry-After) antes de reintentar
| 1 | { |
| 2 | "object": "Error", |
| 3 | "error": { |
| 4 | "code": "VALIDATION_ERROR", |
| 5 | "message": "Invalid request data", |
| 6 | "details": [ |
| 7 | { |
| 8 | "code": "custom", |
| 9 | "path": ["parcel"], |
| 10 | "message": "Send `parcel` for a single box, or `parcels` for a multi-piece shipment." |
| 11 | } |
| 12 | ] |
| 13 | } |
| 14 | } |
Cada endpoint añade los suyos: una compra de etiqueta puede devolver DESTINATION_PHONE_REQUIRED o CUSTOMS_REQUIRED. Trata un código desconocido según su clase de estado HTTP.
El presupuesto pertenece a su organización, no a una clave: todas las claves de API y usuarios de la cuenta comparten el mismo.
Se cuenta en ventanas fijas. El presupuesto diario se reinicia a las 00:00 UTC y un 429 incluye la cabecera Retry-After.
¿Necesita un límite mayor? Escriba a [email protected]: los límites se amplían por cuenta.