Errores

Los errores usan el código HTTP que corresponde y siempre el mismo cuerpo: un code estable, pensado para tu código, y un message legible, en inglés, para tus registros.

404

{
  "error": {
    "code": "not_found",
    "message": "Project not found"
  }
}

Los 500 añaden un request_id:

500

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "0b6f1c8e-2d4a-4e9b-9f3c-7a1d5e8c2b40"
  }
}

Decide en función de error.code, no del texto de message: el texto puede cambiar, el código no.

Códigos

HTTP	code	Qué significa
400	`invalid_parameter`	Un parámetro no vale: un estado que no existe, una fecha mal escrita o un id de filtro (project_id…) que no es un UUID. El mensaje dice cuál.
400	`invalid_cursor`	El cursor no es uno que hayamos dado (cortado o modificado).
400	`invalid_body`	El cuerpo de la petición no es JSON válido (crear webhook).
400	`invalid_url`	La URL del webhook no empieza por http:// o https://.
400	`url_not_allowed`	La URL del webhook apunta a una red interna (localhost, IP privada…).
400	`no_events`	El webhook no tiene ningún evento.
400	`invalid_events`	Algún evento del webhook no existe.
401	`missing_credentials`	Falta la cabecera Authorization: Bearer …
401	`invalid_key_format`	La key no empieza por bn_live_.
401	`invalid_key`	La key no existe.
401	`revoked`	La key se ha revocado.
401	`expired`	La key ha caducado.
402	`trial_expired`	Ha terminado el periodo de prueba.
402	`payment_pending`	El pago de la suscripción no se ha completado.
402	`payment_required`	Hay un recibo impagado o la suscripción está cancelada.
403	`insufficient_scope`	A la key le falta el permiso del endpoint (el mensaje dice cuál).
403	`org_not_found`	La organización de la key ya no existe.
404	`not_found`	No existe, o es de otra organización (se responde igual a propósito).
429	`rate_limited`	Más de 60 peticiones en el mismo minuto. Mira la cabecera Retry-After.
500	`internal_error`	Fallo nuestro. Lleva un request_id: inclúyelo si nos escribes.
503	`not_available`	Esa parte de la API se está activando. Prueba más tarde.

Qué hacer

400: corrige la petición; repetirla igual dará lo mismo.
401 / 403: revisa la key y sus permisos en Configuración → Integraciones.
402: la suscripción tiene que estar al día; avisa al administrador de la cuenta.
429: espera lo que diga Retry-After y reintenta.
500 / 503: reintenta más tarde, esperando cada vez un poco más (1 s, 5 s, 30 s…).