ErroresPróximamente
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.
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
{
"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"
}
}Campo
Tipo
Tres hábitos hacen que los errores no den problemas:
- Decide según
code, no segúnmessage. 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
codeque no conoces, recurre a sutypey a su estado HTTP. Untypedesconocido se trata comoapi_error. - Registra el id de solicitud. Consulta ids de solicitud.
Códigos de estado
| Estado | Tipo | Significado | ¿Reintentar? |
|---|---|---|---|
202 | Ninguno | No es un error. Una acción final 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
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, inclúyelo: le permite a Matchai encontrar exactamente qué pasó con esa solicitud.
Matchai-Request-Id: req_7Hq2LmZ9xV4cReintenta de forma segura
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-Keyen cadaPOST. 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.
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
Cada código de abajo es el destino del doc_url que lo acompaña.
Solicitudes no válidas
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
token_expired
401 · authentication_error. El token de acceso venció. Con Conectar con 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 nueva, o haz que el profesional vuelva a pasar por el flujo de conexión.
Energía
La Energía Matchai nunca es un número en la API. Estos errores solo dicen que no hay suficiente.
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
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
scope_missing
403 · permission_error. La clave o el token es válido, pero le falta el alcance que necesita esta acción. El message lo nombra. Crea una clave de API nueva que incluya el alcance, o haz que el profesional vuelva a pasar por el flujo de conexión con una lista de alcances más larga.
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
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
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
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
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
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
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
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
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
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
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
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_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.
Errores de Matchai
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 con el id de solicitud.