Errores

Todo error sale con la misma forma. Programa contra code: es un valor estable, mientras que message puede cambiar de redacción.

{ "error": true, "code": "validation_error", "message": "Hay campos inválidos.",
  "fields": { "address.zone_id": "La comuna no pertenece a la florería.",
              "products.0.price": "Asegúrese de que este valor es mayor o igual a 0." } }

• fields aparece en los errores de validación, con la ruta de cada campo (address.zone_id, products.0.name).
• Algunos errores agregan datos: required_scope, retry_after, pending_count, pending_limit, status, order_id.
• Los avisos (warnings) de un pedido creado no son errores: ver Pedidos.

Códigos

HTTP	code	Qué pasó	Qué hacer
401	invalid_api_key	La key falta, está mal escrita o no existe.	Revisa el header Authorization: Bearer rf_live_…. Si la perdiste, crea otra en el panel.
401	api_key_revoked	La key fue revocada.	Crea una key nueva en Integraciones del panel.
401	api_key_expired	La key pasó su fecha de expiración.	Crea una key nueva en Integraciones del panel.
403	api_access_disabled	Tu florería no tiene la API incluida en su plan (o la perdió al cambiar de plan).	Habla con Redfloral para habilitarla. Mientras tanto ninguna key funciona.
403	insufficient_scope	La key no tiene el scope que pide la operación. La respuesta trae required_scope.	Agrega el scope a la key en el panel o usa otra key.
403	orders_write_disabled	Tu florería no tiene habilitado el ingreso de ventas locales, así que la API no puede crear ni cancelar pedidos.	Habla con Redfloral. Las lecturas y la subida de documentos siguen funcionando.
400	validation_error	Hay campos inválidos o el cuerpo no es JSON válido. fields trae cada campo con su motivo (address.zone_id, products.0.name…).	Corrige los campos y reintenta.
404	not_found	El recurso no existe o no es de tu florería.	Revisa el id. Un pedido por tu número va con prefijo: /orders/ext:WC-10452.
405	method_not_allowed	La ruta existe pero no acepta ese método HTTP.	Revisa el método en la referencia.
415	unsupported_media_type	El Content-Type no es el que espera la operación.	Usa application/json, salvo para subir documentos (multipart/form-data).
429	rate_limited	Superaste el límite de solicitudes de la key. Trae retry_after y el header Retry-After.	Espera esos segundos y usa lo último que guardaste. Ver Límites.
422	internal_orders_blocked	Tienes excedentes de venta local sin liquidar hasta el límite del plan. Trae pending_count y pending_limit. No se creó nada.	Liquida los pendientes. Ver Cupo y excedente.
409	order_not_cancellable	El pedido no se puede cancelar: no lo creó la API o ya pasó de pending/processing. Trae status.	Pídele a la florería que lo gestione desde el panel.
503	service_unavailable	Error de configuración del lado de Redfloral.	Reintenta más tarde y avisa al equipo de Redfloral.
409	webhook_limit_reached	Ya tienes el máximo de 10 webhooks.	Elimina uno o usa uno con más eventos.
409	idempotency_conflict	La Idempotency-Key ya se usó con otro cuerpo, o hay otra solicitud en curso con ella.	Usa una key nueva para un cuerpo distinto; si es la misma solicitud, espera y reintenta.
409	duplicate_document	El folio ya está en otro pedido de tu florería con el mismo tipo de documento. Trae order_id.	Revisa el folio o el pedido indicado.
400 / 500	error	Error genérico no clasificado.	Reintenta; si se repite, avisa a Redfloral con la hora y el endpoint.

Si aparece un code que tu integración no conoce, trátalo según el código HTTP: la lista puede crecer, pero nunca cambia el significado de un código existente.