---
title: Conceptos básicos de la API
description: URL base, permisos de las claves de API, lista de errores, límites de peticiones, claves de idempotencia y paginación de la API de BillionSend.
seo:
  title: Autenticación y errores de la API
ai:
  exclude: true
---

Las páginas de endpoints de la [referencia de la API](/docs/es/api-reference) se generan a partir de las definiciones de rutas de la API. La [especificación OpenAPI 3.1](/docs/api.openapi.json) es la misma fuente en un solo archivo JSON.

La API es compatible con la API de Resend: mismas rutas, mismos formatos de petición y de error. Llámala desde los [SDK](/docs/es/sdks) de BillionSend o con HTTP directo.

## URL base

`https://api.billionsend.com`

## Autenticación

Envía en cada petición una clave de API de **Claves de API** en el panel:

```
Authorization: Bearer bs_...
```

Una clave ausente o mal formada responde `401 missing_api_key`, y una incorrecta `401 invalid_api_key`.

Una clave tiene un nivel de permiso:

- **Acceso total** puede usar todos los endpoints.
- **Solo envío** solo puede enviar. Todo lo que queda fuera de `/emails` responde `403 restricted_api_key`, y lo mismo vale para `GET /emails`, `GET /emails/{id}`, `GET /emails/metrics`, `DELETE /emails/{id}` y todos los endpoints de `/emails/receiving`, porque devuelven contenido almacenado.

Una clave también se puede limitar a **un dominio** o a **una [bandeja de entrada](/docs/es/inboxes)**. Una clave limitada a un dominio trabaja dentro de él: solo envía desde ese dominio, solo lee su correo, solo ve y cambia ese dominio en `/domains`, y responde `403 restricted_api_key` en todo lo que pertenece al equipo entero (webhooks, supresiones, plantillas, propiedades de contacto, `/usage`, `/deliverability`, verificaciones, `POST /domains`); consulta [Claves de API](/docs/es/api-keys). Una clave que creas con la API nunca es más amplia que la clave que la creó.

Un equipo puede tener 25 claves activas. Las acciones que requieren una clave creada por un propietario o administrador se listan en [Roles del equipo](/docs/es/team-roles).

## Errores

Todo error tiene esta forma:

```json
{ "statusCode": 422, "name": "validation_error", "message": "..." }
```

| Estado y nombre | Significado |
| --- | --- |
| `400 invalid_parameter` | El cuerpo no es un JSON válido. |
| `401 missing_api_key` / `invalid_api_key` | Sin clave, o clave incorrecta. |
| `403 restricted_api_key` | El permiso o el ámbito de la clave no lo permite. |
| `403 forbidden` | Tu rol o tu clave no permite esta acción. |
| `403 plan_limit_reached` | Alcanzaste un límite de tu plan. Consulta [Planes y límites](/docs/es/billing). |
| `403 sending_paused` | El envío está en pausa porque tu tasa de rebotes o de quejas es demasiado alta. |
| `404 not_found` | El endpoint, o lo que pediste, no existe. |
| `409 invalid_idempotent_request` | La clave de idempotencia se usó con otro contenido. |
| `415` | El cuerpo no es `application/json`. |
| `422 validation_error` | La petición no es válida. El mensaje dice por qué. |
| `422 all_recipients_suppressed` | Todos los destinatarios están suprimidos o se han dado de baja. Consulta [Supresiones](/docs/es/concepts/suppressions). |
| `429 rate_limit_exceeded` | Demasiadas peticiones. |
| `429 daily_quota_exceeded` / `monthly_quota_exceeded` | Se agotó la cuota de envío de tu plan. Consulta [Planes y límites](/docs/es/billing). |
| `503 service_unavailable` | El almacén de estadísticas no respondió. El envío no se ve afectado. |

Todo `429` lleva una cabecera `retry-after`: los segundos que hay que esperar.

Toda respuesta, sea de error o no, lleva una cabecera `x-request-id`: el id de la petición, el mismo que tiene en la página Registros del panel. Indícalo cuando nos consultes por una petición.

Un destinatario cuyo dominio nunca puede recibir correo, como `x@example.com`, `x@foo.test` o `x@gmail.con`, se rechaza con `422 validation_error`. Lo mismo vale para un contacto nuevo con esa dirección. Para probar sin escribir a nadie, envía a `success@simulator.amazonses.com`.

La [recepción](/docs/es/receiving), las [bandejas de entrada](/docs/es/inboxes) y la [seguridad del agente](/docs/es/agent-safety) añaden errores propios, que esas páginas listan.

## Límites de peticiones

Cada clave de API puede hacer 600 peticiones por minuto, y las claves de un equipo juntas 3000. Por encima del límite recibes `429 rate_limit_exceeded` y una cabecera `retry-after`. Más de 20 autenticaciones fallidas por minuto desde una misma dirección IP se rechazan del mismo modo.

## Idempotencia

`POST /emails` y `POST /emails/batch` admiten una cabecera `Idempotency-Key` de 1 a 256 caracteres. También las respuestas, los reenvíos y los envíos de borrador de las bandejas de entrada, y las respuestas y los reenvíos de correo recibido. Si reintentas con la misma clave y el mismo contenido, obtienes la respuesta original en lugar de un segundo email. La misma clave con otro contenido responde `409`.

## Paginación

Los endpoints de lista admiten `limit` (de 1 a 100, 20 por defecto) y los cursores `after` y `before`, cada uno un id de elemento de una página anterior. La respuesta incluye `has_more`. Las listas van del más reciente al más antiguo:

- `after` recibe el último id de una página y devuelve elementos más antiguos.
- `before` recibe el primer id y devuelve elementos más recientes.

Para ponerte al día con lo nuevo, pasa como `before` el id más reciente que guardaste.

Algunas listas siguen otro orden, que indican sus páginas de referencia: los hilos de una bandeja (actividad más reciente primero), los emails de un hilo (del más antiguo al más reciente), y los temas y las etiquetas (del más antiguo al más reciente, todos de una vez). Un cursor que no coincide con ningún elemento responde `422 validation_error` (`404` bajo `/inboxes`).

## Reglas que conviene conocer

- **Los adjuntos** admiten solo `content` en base64 incrustado. Una URL `path` remota responde `422`. Los adjuntos suman hasta 10 MiB por email, y el email entero debe quedar por debajo de 40 MB. Los programas y scripts (`.exe`, `.js`, `.bat` y similares, también dentro de un ZIP) se rechazan siempre. En un equipo nuevo, algunos tipos de riesgo, como archivos comprimidos, páginas web y archivos de Office con macros, se aceptan pero esperan una revisión antes de enviarse.
- **Los contactos** pertenecen al equipo. No hay audiencias: los endpoints de audiencia funcionan como alias de los [segmentos](/docs/es/concepts/segments).
- **Las bajas** pertenecen al dominio de envío. Consulta [Bajas](/docs/es/concepts/unsubscribes).
- **Destinatarios**: `to`, `cc` y `bcc` juntos admiten hasta 50 direcciones, cada una un solo buzón. Un envío en el que todas las direcciones de `to` están suprimidas responde `422 all_recipients_suppressed`.
- **Las cabeceras** tienen lista de permitidas: cualquier nombre `X-*` (salvo `X-SES-*` y `X-BillionSend-*`), cabeceras de hilos y de prioridad, y el par `List-Unsubscribe`. Cualquier otra responde `422`.
- **Los asuntos** pueden tener hasta 998 caracteres.
- **Endpoints adicionales**: `GET /usage` (plan, límites y uso), `DELETE /emails/{id}` y `GET /emails/metrics` ([Analíticas](/docs/es/concepts/analytics)).
- **Contactos en bloque**: `POST /contacts/batch` crea y `POST /contacts/batch/remove` elimina hasta 1000 contactos en una petición. `include=properties,topics` en las listas de contactos añade las propiedades y los temas de cada contacto.
- **Las supresiones en bloque** admiten hasta 1000 direcciones por petición.
- **Estados adicionales**: los envíos masivos pueden quedar `canceled`.
- **La recepción y las bandejas de entrada** están en beta, con long-polling y un flujo de eventos en directo para el correo nuevo. Consulta [Recepción](/docs/es/receiving) y [Bandejas de entrada](/docs/es/inboxes).
- **Los ajustes no admitidos** se rechazan con `422` en lugar de ignorarse en silencio.

## Enlaces de descarga firmados

El correo recibido lleva enlaces de descarga del mensaje original y de sus adjuntos. Son URL `GET` sencillas que no necesitan clave de API, funcionan una hora y responden `403` cuando caducan. Pide a la API un enlace nuevo. Consulta [Recepción](/docs/es/receiving).
