# Errores y límites

## Errores

Todos tienen la misma forma:

```json
{
  "error": {
    "type": "permission_error",
    "code": "not_team_member",
    "message": "No tienes acceso a este equipo."
  },
  "request_id": "req_8f2a4c1b9e6a1d34"
}
```

El `request_id` también viene en la cabecera `X-Request-Id`. Si algo va mal y no
sabes por qué, mándanoslo: con él podemos encontrar exactamente qué pasó.

| `type` | HTTP | Cuándo |
|---|---|---|
| `invalid_request_error` | 400 | El cuerpo o los parámetros no son válidos |
| `authentication_error` | 401 | Falta la key, o está revocada o expirada |
| `permission_error` | 403 | La key no tiene el scope, o tu rol no alcanza |
| `not_found_error` | 404 | No existe |
| `rate_limit_error` | 429 | Demasiadas peticiones, o cuota de IA agotada |
| `api_error` | 500 | Fallo nuestro |

Un detalle a propósito: pedir un equipo **al que no perteneces** devuelve `403`, no
`404`. Si devolviéramos `404` solo cuando el equipo no existe, la API se convertiría
en una forma de averiguar qué equipos existen.

## Límites de peticiones

Por minuto, según el plan del equipo mejor posicionado al que perteneces:

| Plan | Peticiones por minuto |
|---|---|
| Free | 30 |
| Essential | 60 |
| Pro | 120 |
| Max | 300 |

Cada respuesta te dice cómo vas:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1784553600
```

Si te pasas, la API responde `429` con `Retry-After` (en segundos) además de las
cabeceras de arriba.

## Cuota de IA

Los endpoints de IA (`/ai/ask`, `/ai/plan-sprint`) y las herramientas `ask_team` y
`plan_sprint_from_text` consumen la **misma cuota mensual de IA que la app**. No hay
un contador aparte, ni cargos sorpresa: cuando se agota, se agota, y la API devuelve
`429` con `code: quota_exceeded`.

Puedes ver cuánto te queda:

```bash
curl https://notiq.online/api/v1/teams/TEAM_ID/usage \
  -H "Authorization: Bearer ntq_sk_tu_key"
```

## Paginación

Las listas se paginan con un cursor:

```bash
curl "https://notiq.online/api/v1/teams/TEAM_ID/activities?limit=50" \
  -H "Authorization: Bearer ntq_sk_tu_key"
```

```json
{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "a3f1…"
}
```

Para la siguiente página, pasa ese cursor en `starting_after`. El máximo de `limit`
es 100; el valor por defecto, si no lo mandas, es 25.