> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finup.ar/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenciones y errores

> Formato de datos, paginación, fechas y códigos de error de la API.

# Convenciones y errores

## Base URL

```text theme={null}
https://api.finup.ar
```

## Formato

* Todo es **JSON** (`Content-Type: application/json`), salvo la subida de
  archivos (`multipart/form-data`).
* Los nombres de campos van en **snake\_case** (`first_name`, `due_date`).
* Los **montos** son números (no strings).
* Las **fechas y horas** son ISO 8601 UTC (`2026-01-14T12:00:00.000Z`), salvo
  los vencimientos de cuota, que son fechas (`2026-02-10`).
* Los identificadores son **UUID**.

## Paginación

Los listados grandes usan **cursor**:

```bash theme={null}
curl "https://api.finup.ar/api/clients?limit=50" -H "Authorization: Bearer $KEY"
```

La respuesta trae `nextCursor`. Para la página siguiente, pasalo tal cual:

```bash theme={null}
curl "https://api.finup.ar/api/clients?limit=50&cursor=$NEXT" -H "Authorization: Bearer $KEY"
```

`nextCursor: null` significa que no hay más resultados.

## Errores

Todos los errores tienen la misma forma:

```json theme={null}
{ "error": "Mensaje legible" }
```

| Status | Significado |
| - | - |
| `400 Bad Request` | Faltan datos o son inválidos (por ejemplo, sin `amount`). |
| `401 Unauthorized` | Clave ausente o inválida. |
| `403 Forbidden` | Clave de solo lectura, o falta de permisos. |
| `404 Not Found` | El recurso no existe **o no pertenece a tu negocio**. |
| `409 Conflict` | Duplicado (por ejemplo, un DNI que ya existe). |
| `502 / 503` | Error de un servicio externo (ARCA/BCRA) o servicio no configurado. |

<Note>
  Un `404` no distingue "no existe" de "es de otro negocio": la API nunca revela
  datos de otros negocios.
</Note>

## Escrituras

* Las operaciones de escritura requieren una clave de **acceso total**.
* No hay endpoints idempotentes con clave de idempotencia: si reintentás una
  creación (por ejemplo, un pago), podés duplicar el registro. Diseñá tus
  reintentos con cuidado.

## Límites

Hoy no hay límite de requests por minuto. Se recomienda no superar
\~5–10 requests por segundo por negocio.