Skip to main content
La Developer API usa códigos de estado HTTP convencionales y devuelve un cuerpo JSON en cada error. El cuerpo incluye un _tag estable sobre el que puede ramificar su lógica, un message pensado para sus registros y una línea feedback que indica dónde reportar el error si no le dice qué debe cambiar:
Ramifique según _tag (y code, cuando exista), nunca según el texto de message: los mensajes pueden cambiar, las etiquetas no.

​
Códigos de estado

Los cuerpos 4xx pueden mostrarse sin riesgo en sus propios registros y paneles. Las respuestas 5xx deben reintentarse con retroceso: los endpoints de decisión de pedidos y de reproducción de webhooks son seguros ante reintentos, así que reintentarlos no causa daño. Si un error no le dice qué debe cambiar, o si la API hace algo que estas docs dicen que no debería, envíe comentarios y cite el x-request-id de la solicitud.

​
Etiquetas de error

DeveloperApiUnprocessable es un 422 que incluye code, message y, opcionalmente, details. DeveloperApiRateLimited es un 429 que incluye retry_after en segundos y el encabezado HTTP Retry-After correspondiente.

​
Códigos de error de reservas

Los cuerpos de las operaciones de reservas que modifican datos rechazan los campos desconocidos con 400, incluidos los campos opcionales mal escritos, como expectedVersion en lugar de expected_version. Las claves de idempotencia deben tener entre 1 y 255 caracteres.
  • 400: invalid_slot_token, expired_slot_token, invalid_window, invalid_cursor, invalid_phone, location_required, change_required, invalid_blackout_dates; los errores de esquema de configuración incluyen las rutas de validación.
  • 409: stale_version (details.expected/actual), stale_blackout_dates, stale_configuration, idempotency_key_reused, overlapping_booking, slot_unavailable, hold_expired, hold_consumed, not_changeable, not_cancellable, illegal_transition (details.from_status), waitlist_closed, operation_in_progress (details.operation_id, details.retry_after, details.reason).
  • 422: bookings_not_enabled, party_size_out_of_bounds, outside_booking_window, large_party_inquiry_required, date_blocked, capability_unsupported, guest_contact_required, guest_messaging_unavailable, payment_instrument_required, configuration_missing, configuration_rejected, provider_rejected.
Con operation_in_progress, reintente la solicitud original con su clave original. Si details.reason es replay_window_expired, detenga los reintentos automáticos y contacte a Maple con el ID de la operación. Nunca use una clave nueva para evitar un resultado incierto del proveedor. Consulte Tome reservas. provider_rejected es definitivo: el proveedor rechazó la solicitud y nada cambió. Por ejemplo, es posible que OpenTable no permita cambiar ni cancelar una reserva a través de Maple; el establecimiento sí puede cambiarla. Reintentar produce la misma respuesta. Cuando el proveedor indica por qué la rechazó, recibe el código con el que respondería un local nativo de Maple en la misma situación, y no provider_rejected:
  • un horario demasiado cercano para reservar o al cual mover la reserva: 422 outside_booking_window con details.reason: inside_min_lead;
  • una reserva que ya comenzó o está por comenzar: 409 not_changeable o 409 not_cancellable con details.reason: outside_policy_window;
  • un horario que requiere una tarjeta que el proveedor no puede tomar a través de Maple: 422 payment_instrument_required.
Estos también son definitivos, y nada cambió.

​
Los códigos 403

Un DeveloperApiForbidden siempre le dice por qué:
  • insufficient_scope: la credencial es válida pero carece de un alcance que el endpoint requiere. Compare GET /v1/me con la tabla de alcances.
  • wrong_environment: usó una credencial de prueba con datos en vivo o al revés. El prefijo de la credencial determina su entorno.

​
Cómo manejar bien los errores

  • Ramifique según _tag/code y registre el message. La etiqueta es su flujo de control; el mensaje es para las personas que depuran.
  • No reintente 4xx sin cambios. Significan que la solicitud debe cambiar. El único matiz: un 409 puede resolverse una vez que se resuelva el estado en conflicto.
  • Reintente 5xx con retroceso exponencial. Agregue variación aleatoria (jitter) para evitar tormentas de reintentos.
  • Trate los reintentos de escritura como seguros. Las decisiones de pedidos y la reproducción de webhooks son seguras ante reintentos, así que un reintento tras un tiempo de espera agotado no se aplicará dos veces.