---
title: "Errores"
description: "El formato de error de la API de Matchai, cada código con su estado HTTP y qué hacer, qué solicitudes se pueden reintentar y cómo usar los ids de solicitud."
last_updated: "2026-10-21"
lang: "es"
status: "coming-soon"
canonical: "https://matchai.co/docs/es/developers/errors"
---
# Errores
> El formato de error de la API de Matchai, cada código con su estado HTTP y qué hacer, qué solicitudes se pueden reintentar y cómo usar los ids de solicitud.
**Próximamente. Esto se documenta antes del lanzamiento para que puedas planificar tu integración; todavía no está disponible.**
Source: https://matchai.co/docs/es/developers/errors
Todos los errores de la API de Matchai tienen la misma estructura JSON. Decide según el `code`, que es estable, y muéstrale el `message` a la persona que usa tu app: dice qué pasó y qué hacer a continuación.
## El formato de los errores [#the-error-format]
```json title="Response (400)"
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "price.amount must be greater than 0.",
"param": "price.amount",
"doc_url": "https://matchai.co/docs/developers/errors#parameter_invalid",
"request_id": "req_7Hq2LmZ9xV4c"
}
}
```
Tres hábitos hacen que los errores no den problemas:
- **Decide según `code`, no según `message`.** Los códigos son estables. Los mensajes están escritos para personas, siguen el idioma de la cuenta y pueden redactarse de otra forma.
- **Trata los valores desconocidos como desconocidos, no como un fallo.** Se pueden agregar códigos y tipos nuevos sin una versión nueva. Si encuentras un `code` que no conoces, recurre a su `type` y a su estado HTTP. Un `type` desconocido se trata como `api_error`.
- **Registra el id de solicitud.** Consulta [ids de solicitud](#request-ids).
## Códigos de estado [#status-codes]
| Estado | Tipo | Significado | ¿Reintentar? |
|---|---|---|---|
| `202` | Ninguno | No es un error. Una [acción final](https://matchai.co/docs/es/developers/authentication#final-actions) espera la aprobación del titular de la cuenta. Todavía no ha pasado nada. | No. Espera `approval.resolved`. |
| `400` | `invalid_request_error` | La solicitud está mal formada o un parámetro no es válido. | No. Corrige la solicitud. |
| `401` | `authentication_error` | Falta la clave o el token, o venció, fue revocado o es incorrecto. | Una vez, después de renovar un token vencido. |
| `402` | `energy_error` | No hay suficiente Energía Matchai, o la conexión alcanzó su límite de energía. | No, hasta que vuelva a haber energía. |
| `403` | `permission_error` | La credencial es válida, pero no puede hacer esto. | No. |
| `404` | `not_found_error` | No existe, o esta cuenta no puede verlo. | No. |
| `409` | `conflict_error` | Choca con el estado actual. | No. Cambia la solicitud. |
| `422` | `unprocessable_error` | La solicitud está bien formada, pero infringe una regla del producto. | No. Cambia la solicitud. |
| `429` | `rate_limit_error` | Demasiadas solicitudes para esta conexión. | Sí, después de `Retry-After` segundos. |
| `500` | `api_error` | Algo salió mal del lado de Matchai. | Sí, con el mismo `Idempotency-Key`. |
## Ids de solicitud [#request-ids]
Cada respuesta, exitosa o no, incluye un encabezado `Matchai-Request-Id`. Los errores lo repiten como `error.request_id`. Regístralo con cada llamada fallida. Cuando contactes al [soporte de Matchai](https://matchai.co/support), inclúyelo: le permite a Matchai encontrar exactamente qué pasó con esa solicitud.
```http title="Response header"
Matchai-Request-Id: req_7Hq2LmZ9xV4c
```
## Reintenta de forma segura [#retry-safely]
Reintentar es seguro cuando la misma solicitud puede repetirse sin hacer la acción dos veces. Para eso sirve el encabezado `Idempotency-Key`.
- Envía un `Idempotency-Key` en cada `POST`. Un UUID sirve.
- Un reintento con la **misma clave** dentro de las 24 horas devuelve la primera respuesta en lugar de actuar dos veces. Un reintento de una acción final en modo **Preguntarme** devuelve la misma aprobación pendiente.
- Reutilizar una clave con un **cuerpo diferente** devuelve `409 idempotency_key_reused`. Crea una clave nueva para cada solicitud nueva.
Reintenta los errores de red y los tiempos de espera agotados, `429` y `500`. No reintentes `400`, `403`, `404`, `409` ni `422` sin cambios: vuelven a fallar de la misma forma. Un `402` sigue fallando hasta que la cuenta vuelva a tener energía o el titular de la cuenta aumente el límite de la conexión.
Espera antes de cada reintento: respeta `Retry-After` cuando lo haya y, si no, espera cada vez más, con un poco de aleatoriedad para que muchos clientes no reintenten al mismo tiempo.
```js title="retry.mjs"
import { randomUUID } from 'node:crypto';
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 1 s, 2 s, 4 s... plus up to a second of jitter.
const backoff = (attempt) => 2 ** (attempt - 1) * 1000 + Math.random() * 1000;
export async function postWithRetry(url, body, { attempts = 4 } = {}) {
const idempotencyKey = randomUUID(); // The same key on every attempt.
for (let attempt = 1; ; attempt += 1) {
let response;
try {
response = await fetch(url, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey,
},
body: JSON.stringify(body),
});
} catch (networkError) {
if (attempt >= attempts) throw networkError;
await sleep(backoff(attempt));
continue;
}
const retryable = response.status === 429 || response.status >= 500;
if (!retryable || attempt >= attempts) return response;
const retryAfter = Number(response.headers.get('Retry-After'));
await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
}
}
```
## Códigos de error [#error-codes]
Cada código de abajo es el destino del `doc_url` que lo acompaña.
### Solicitudes no válidas [#invalid-requests]
#### `parameter_invalid` [#parameter_invalid]
**`400` · `invalid_request_error`.** Falta un campo, tiene el tipo incorrecto o está fuera de rango. `param` nombra el campo, con puntos para los campos anidados, como `price.amount`. Corrige la solicitud: si la envías de nuevo sin cambios, vuelve a fallar.
Otras respuestas `400`, como un cuerpo que no es JSON válido, tienen el mismo `type`. Trata cualquier `400` como "esta solicitud es incorrecta".
### Autenticación [#authentication]
#### `token_expired` [#token_expired]
**`401` · `authentication_error`.** El token de acceso venció. Con [Conectar con Matchai](https://matchai.co/docs/es/developers/authentication/connect-with-matchai), intercambia tu token de actualización por un token de acceso nuevo y repite la solicitud una vez. Si la renovación falla, la conexión terminó y el profesional tiene que volver a conectarse.
Un `401` también puede significar que la clave o el token falta, está mal escrito o fue revocado, o que la conexión terminó. Esos casos tienen el mismo `type`. Pide una [clave de API](https://matchai.co/docs/es/developers/authentication/api-keys) nueva, o haz que el profesional vuelva a pasar por el flujo de conexión.
### Energía [#energy]
La Energía Matchai nunca es un número en la API. Estos errores solo dicen que no hay suficiente.
#### `insufficient_energy` [#insufficient_energy]
**`402` · `energy_error`.** La cuenta no tiene suficiente Energía Matchai para esta acción. No se hizo nada y no se gastó nada. El titular de la cuenta puede obtener más en Matchai Store, y `GET /v1/me` informa el estado de su energía (`full`, `comfortable`, `low` o `empty`). Muéstrale el `message` a la persona, y vuelve a intentarlo cuando haya recargado.
#### `energy_limit_reached` [#energy_limit_reached]
**`402` · `energy_error`.** Esta conexión usó todo el límite de energía que el titular de la cuenta le fijó. No se hizo nada y no se gastó nada. `GET /v1/me/connection` informa `energy_limit_reached: true`. El titular de la cuenta decide si aumenta el límite; tu app no debe reintentar en bucle.
### Permisos [#permissions]
#### `scope_missing` [#scope_missing]
**`403` · `permission_error`.** La clave o el token es válido, pero le falta el [alcance](https://matchai.co/docs/es/developers/authentication#scopes) que necesita esta acción. El `message` lo nombra. Crea una [clave de API](https://matchai.co/docs/es/developers/authentication/api-keys) nueva que incluya el alcance, o haz que el profesional vuelva a pasar por el [flujo de conexión](https://matchai.co/docs/es/developers/authentication/connect-with-matchai) con una lista de alcances más larga.
#### `not_allowed` [#not_allowed]
**`403` · `permission_error`.** El rol de la cuenta no permite esto. La conexión actúa con los permisos propios del titular de la cuenta y nada más, así que lo que no puede hacer en Matchai, como editar el trabajo de un equipo siendo miembro sin derechos de edición, tampoco puede hacerlo a través de tu app. Díselo a la persona y no reintentes.
### No encontrado [#not-found]
#### `resource_not_found` [#resource_not_found]
**`404` · `not_found_error`.** El elemento no existe, o esta cuenta no puede verlo. Matchai da la misma respuesta en ambos casos, así que una respuesta nunca confirma que algo existe en la cuenta de otra persona. Revisa el id, y comprueba que estás usando la credencial de la cuenta que querías.
### Conflictos [#conflicts]
#### `contact_exists` [#contact_exists]
**`409` · `conflict_error`.** El correo electrónico o el número de teléfono que enviaste ya pertenece a uno de los contactos de la cuenta, así que no se agregó nada. El id del contacto existente está en `error.param`. Actualiza ese contacto, o usa `POST /v1/enquiries`, que encuentra los contactos existentes por ti.
#### `subdomain_taken` [#subdomain_taken]
**`409` · `conflict_error`.** El subdominio que pediste no está disponible. Los subdominios usan letras minúsculas, dígitos y guiones. Elige otro y vuelve a intentarlo.
#### `calendar_conflict` [#calendar_conflict]
**`409` · `conflict_error`.** El horario se superpone con otra cita, y la respuesta enumera las citas con las que choca. Ofrece otro horario. Envía `book_over_conflict: true` solo cuando el titular de la cuenta haya aceptado la superposición.
#### `slot_unavailable` [#slot_unavailable]
**`409` · `conflict_error`.** El horario que pediste se ocupó mientras tanto, por ejemplo entre el momento en que le mostraste a un visitante los horarios libres y el momento en que registraste su solicitud de visita. Vuelve a obtener los horarios libres y ofrece otro.
#### `idempotency_key_reused` [#idempotency_key_reused]
**`409` · `conflict_error`.** Enviaste un `Idempotency-Key` que Matchai ya había recibido en las últimas 24 horas, con un cuerpo de solicitud diferente. Usa una clave nueva para cada solicitud nueva. Reutiliza una clave solo para repetir exactamente la misma solicitud.
### Rechazado por una regla del producto [#refused-by-a-product-rule]
#### `rooms_exceed_count` [#rooms_exceed_count]
**`422` · `unprocessable_error`.** El número de habitaciones o de baños de un anuncio no puede ser menor que el de las habitaciones registradas en él. Elimina primero la habitación y luego reduce el número. `param` nombra el campo, como `property.bedrooms`.
#### `recipient_suppressed` [#recipient_suppressed]
**`422` · `unprocessable_error`.** Matchai no enviará correos electrónicos a esta dirección, porque mensajes anteriores rebotaron o se marcaron como no deseados. Díselo a la persona, y comunícate con el contacto de otra forma.
#### `contact_blocked` [#contact_blocked]
**`422` · `unprocessable_error`.** Este contacto está bloqueado, así que Matchai se niega a enviarle mensajes. Díselo a la persona y no reintentes.
#### `content_not_allowed` [#content_not_allowed]
**`422` · `unprocessable_error`.** El contenido que enviaste infringe las reglas de contenido de Matchai. El `message` dice qué cambiar. No lo reintentes sin cambios.
#### `handle_not_routable` [#handle_not_routable]
**`422` · `unprocessable_error`.** No se pudo publicar la Página Matchai porque el nombre de usuario de la cuenta todavía no puede ser una dirección web. El titular de la cuenta tiene que elegir otro nombre de usuario en Matchai.
### Límites de solicitudes [#rate-limits]
#### `rate_limited` [#rate_limited]
**`429` · `rate_limit_error`.** Demasiadas solicitudes para esta conexión. La respuesta incluye `Retry-After`, la cantidad de segundos que debes esperar. Consulta [límites de solicitudes](https://matchai.co/docs/es/developers/rate-limits#in-the-matchai-api).
### Errores de Matchai [#matchai-errors]
#### `internal_error` [#internal_error]
**`500` · `api_error`.** Algo salió mal del lado de Matchai. Es seguro reintentar con el mismo `Idempotency-Key`, unas cuantas veces, con esperas cada vez más largas. Si sigue fallando, contacta al [soporte de Matchai](https://matchai.co/support) con el id de solicitud.
Cómo se limitan las solicitudes, y cómo mantenerte por debajo del límite.
Alcances, acciones finales y límites de energía.
Los errores que puede devolver cada endpoint.
## Sitemap
- [Todas las páginas de la documentación de Matchai](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/es/llms.txt)