> For the complete documentation index, see [llms.txt](https://docs.zipnova.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zipnova.com/carriers/referencia-api/convenciones-y-errores.md).

# Convenciones y errores

Servidores, autenticación con API key, unidades, paginación y códigos de respuesta de la API del Carrier.

## Servidores

La API está disponible por país. Usa el servidor del país donde opera tu Carrier.

| País           | URL base                                |
| -------------- | --------------------------------------- |
| Argentina (AR) | `https://api.zipnova.com.ar/carrier/v1` |
| Chile (CL)     | `https://api.zipnova.cl/carrier/v1`     |
| México (MX)    | `https://api.zipnova.com.mx/carrier/v1` |

## Autenticación

Cada Carrier tiene su propia API key, que se genera desde el Carrier Hub y se puede rotar manualmente. Envíala en cada pedido como token Bearer:

```bash
curl https://api.zipnova.com.ar/carrier/v1/me \
  -H "Authorization: Bearer $API_KEY"
```

{% hint style="warning" %}
La API key identifica a tu Carrier: guárdala como un secreto y no la expongas en aplicaciones cliente. Si se filtra, rótala desde el Carrier Hub.
{% endhint %}

Para las llamadas en sentido contrario, de Zipnova a tu Carrier, ver [Validar la firma de Zipnova](/carriers/endpoints/validar-la-firma-de-zipnova.md).

## Formatos y unidades

| Dato           | Formato                              |
| -------------- | ------------------------------------ |
| Fechas y horas | ISO 8601.                            |
| Pesos          | Gramos.                              |
| Dimensiones    | Centímetros.                         |
| Volúmenes      | cm³.                                 |
| Importes       | En la moneda del país.               |
| Código postal  | No se envía en Chile.                |
| Documento      | DNI, CUIT, RUT o RFC, según el país. |

## Paginación

`GET /shipments` devuelve 50 envíos por página.

* Sin `updated_since` ni `created_since`, se pagina con `page`.
* Con `updated_since` o `created_since`, el listado va del más antiguo al más reciente y se pagina con `cursor`, tomado de `meta.next_cursor` de la página anterior.

## Códigos de respuesta

| Código | Cuándo ocurre                                                                                                                    |
| ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | La API key es inválida o la organización está suspendida.                                                                        |
| `404`  | El recurso no existe o no pertenece a tu Carrier.                                                                                |
| `409`  | El estado actual del envío no permite la operación: no está documentado, está en un estado final o tu Carrier usa Zipnova Rutas. |
| `422`  | Los datos enviados son inválidos.                                                                                                |
| `429`  | Superaste el límite de pedidos. Reintenta con una espera creciente.                                                              |