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

# Errores y límites

> Qué devuelve la API cuando algo sale mal, y cuántas peticiones puedes hacer.

## Errores

Todos tienen la misma forma:

```json theme={null}
{
  "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                                 |

<Note>
  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.
</Note>

## 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 theme={null}
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:

<CodeGroup>
  ```bash Petición theme={null}
  curl "https://notiq.online/api/v1/teams/TEAM_ID/activities?limit=50" \
    -H "Authorization: Bearer ntq_sk_tu_key"
  ```

  ```json Respuesta theme={null}
  {
    "data": [ … ],
    "has_more": true,
    "next_cursor": "a3f1…"
  }
  ```
</CodeGroup>

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.