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

HTTPcodeCuándo pasaQué hacer
400invalid_parameterUn 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.
401unauthorizedFalta 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.
403forbiddenLa 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.
403api_not_enabledLa API no está habilitada para tu empresa, o se suspendió.Escribí a api@marimpex.com.ar para habilitarla.
403account_inactiveLa cuenta de tu empresa está inactiva.Escribí a api@marimpex.com.ar.
404not_foundEl 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.
404pdf_not_availableEl comprobante existe pero no tiene PDF disponible.Reintentá más tarde. Si persiste, escribinos con el id del comprobante.
409ret_not_availableEl 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.
429rate_limitedSuperaste 60 llamadas por minuto por clave o 300 por minuto por IP.Esperá los segundos del header Retry-After y reintentá.
500internal_errorError 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.