Errores

Todos los errores usan el formato estándar RFC 7807 (Content-Type: application/problem+json) con un campo adicional code, estable, que debes usar en tu lógica en lugar del texto del mensaje.

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Start date cannot be in the past",
  "code": "INVALID_REQUEST"
}

Los errores de validación incluyen además errors, con el campo que falla y el motivo (nunca el valor enviado):

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "errors": { "token": "must not be blank" }
}

Códigos

Estado	code	Cuándo ocurre	Qué hacer
400	VALIDATION_ERROR	Un campo del cuerpo falta o no es válido.	Corrige el campo indicado en errors.
400	INVALID_BODY	El cuerpo falta o no es un JSON válido.	Revisa el formato del JSON y las fechas (yyyy-MM-dd).
400	INVALID_PARAMETER	Un parámetro de la URL tiene un formato incorrecto.	Corrige el parámetro.
400	MISSING_PARAMETER	Falta un parámetro obligatorio de la URL.	Añádelo.
400	INVALID_TOKEN	El token del prebooking no es válido.	Repite la búsqueda de disponibilidad y usa el token que devuelve.
400	INVALID_REQUEST	La petición es válida pero no se puede atender, por ejemplo una fecha de inicio en el pasado.	Lee detail.
401	UNAUTHORIZED	Credenciales ausentes, incorrectas o desactivadas.	Revisa usuario, secreto y entorno.
404	NOT_FOUND	El plan del token ya no está activo o ya no se vende como eSIM.	Repite la búsqueda de disponibilidad.
404	PREBOOKING_NOT_FOUND	El prebooking no existe o no es de tu cuenta.	Haz un prebooking nuevo.
404	SALE_NOT_FOUND	La venta no existe o no es de tu cuenta.	Revisa el localizador.
404	VOUCHER_NOT_AVAILABLE	La venta es tuya pero no tiene voucher.	Contacta con soporte.
409	NO_STOCK	No hay suficientes eSIM disponibles.	Reduce la cantidad o prueba más tarde.
409	CARDS_NUMBER_MISMATCH	Las eSIM del prebooking se han agotado antes de confirmar.	Haz un prebooking nuevo.
415	UNSUPPORTED_MEDIA_TYPE	El Content-Type no es application/json.	Envía Content-Type: application/json.
500	INTERNAL_ERROR	La petición no se ha podido procesar por un problema nuestro.	Reintenta pasados unos segundos; si persiste, contacta con soporte indicando el code.
503	SERVICE_UNAVAILABLE	El servicio no ha podido procesar la petición.	Reintenta pasados unos segundos.
5xx	(varios)	Error interno al confirmar la venta.	Reintenta con el mismo prebookingId; si persiste, contacta con soporte indicando el code.

Buenas prácticas

• Decide qué hacer según code, no según detail: el texto puede cambiar.
• Reintenta únicamente los 503 y los 5xx, con espera creciente. Los 4xx no se arreglan reintentando.
• Registra el code y el momento del error cuando contactes con soporte; nunca incluyas el secreto.