Errores
Todos los errores devuelven el mismo formato JSON. Programá tu cliente contra el código HTTP y el campo code, no contra el texto del mensaje.
Formato
{
"error": {
"code": "not_found",
"message": "Despacho no encontrado."
}
}Códigos
| HTTP | code | Cuándo pasa | Qué hacer |
|---|---|---|---|
| 400 | invalid_parameter | Un parámetro es inválido: limit fuera de rango, updated_since que no es ISO 8601, origen distinto de aduana o flete, cursor inválido, o un número de despacho con formato incorrecto. | Corregí el parámetro. El mensaje indica cuál. No reintentes igual. |
| 401 | unauthorized | Falta la clave, es inválida, está vencida o fue anulada. | Revisá el header Authorization y la clave. Si venció o fue anulada, creá una nueva en Mi Organización → API. |
| 403 | forbidden | La clave es válida pero no tiene el permiso del recurso (customs:read o billing:read). | Creá una clave con ese permiso en Mi Organización → API. Si el permiso no aparece, tu empresa no tiene ese módulo: escribí a api@marimpex.com.ar. |
| 403 | api_not_enabled | La API no está habilitada para tu empresa, o se suspendió. | Escribí a api@marimpex.com.ar para habilitarla. |
| 403 | account_inactive | La cuenta de tu empresa está inactiva. | Escribí a api@marimpex.com.ar. |
| 404 | not_found | El despacho o comprobante no existe, no es de tu empresa o todavía no está emitido. Los tres casos responden igual, a propósito. | Verificá el identificador. No hay forma de distinguir los casos. |
| 404 | pdf_not_available | El comprobante existe pero no tiene PDF disponible. | Reintentá más tarde. Si persiste, escribinos con el id del comprobante. |
| 409 | ret_not_available | El despacho existe y es tuyo, pero todavía no tiene el .RET disponible (pasa antes de la oficialización). | Reintentá más tarde. En el listado, esos despachos salen con tieneRet: false. |
| 429 | rate_limited | Superaste 60 llamadas por minuto por clave o 300 por minuto por IP. | Esperá los segundos del header Retry-After y reintentá. |
| 500 | internal_error | Error interno de Marimpex. | Reintentá con espera creciente. Si persiste, escribinos a api@marimpex.com.ar con la hora aproximada. |
Por qué el 401 es genérico
Con cualquier problema de clave, la API responde el mismo 401 con el mismo mensaje. No dice si el identificador existe, si el secreto no coincide o si la clave venció. Es una medida de seguridad: no le da pistas a quien prueba claves al azar. Si tu clave debería andar, verificá que no tenga espacios ni saltos de línea de más, y pedinos una nueva si hace falta.
Qué reintentar
Reintentá solo 429 (respetando Retry-After), 500 y 409 ret_not_available. Los demás 4xx no se arreglan reintentando igual.