Errores

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:

{
  "_tag": "DeveloperApiForbidden",
  "code": "insufficient_scope",
  "message": "Missing required scope: menus:write",
  "feedback": "If this error does not tell you what to change, or the API is wrong, report it with POST /v1/feedback and cite this response's x-request-id: https://docs.maple.inc/developer-api/concepts/feedback"
}

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

Estado	Significado	Qué hacer
400	La solicitud está mal formada o hace referencia a valores no válidos	Corrija la solicitud; no la reintente sin cambios
401	Credencial ausente, mal formada o no reconocida, o app inactiva	Revise el encabezado Authorization y la clave
403	Credencial válida, pero no permitida (vea code más abajo)	Ajuste los alcances (scopes) o el entorno
404	El recurso no existe o no es visible para su credencial	Verifique el id y que esté conectado
409	La solicitud entra en conflicto con el estado actual	Resuelva el conflicto (por ejemplo, el local ya está conectado)
422	Una regla de negocio o una capacidad no compatible impide la operación	Revise code y details; cambie la solicitud o la configuración del local
429	Se alcanzó una cuota o un límite de frecuencia	Espere los segundos de retry_after de la respuesta antes de volver a intentarlo
5xx	Un problema del lado de Maple	Reintente con retroceso exponencial

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

_tag	Estado	Notas
DeveloperApiBadRequest	400	Solicitud mal formada o con valores no válidos, como tipos de evento desconocidos. Cuando los parámetros de ruta, los parámetros de consulta, los encabezados o el cuerpo no pasan la validación, code es invalid_request y el mensaje nombra el campo y lo que se esperaba. En la publicación de menús, el mensaje enumera todos los problemas de validación.
DeveloperApiUnauthorized	401	La credencial bearer falta, está mal formada, venció o pertenece a una app inactiva.
DeveloperApiForbidden	403	Incluye un code: insufficient_scope o wrong_environment.
DeveloperApiNotFound	404	El recurso no existe o su credencial no puede verlo.
DeveloperApiConflict	409	La solicitud entra en conflicto con el estado actual, por ejemplo, al conectar un local que otra app ya tiene.
DeveloperApiInternalError	500	Maple no pudo completar la solicitud. Reintente con retroceso; si persiste, envíe comentarios con el x-request-id.

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.