> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores

> Códigos de estado HTTP estándar con un cuerpo JSON que incluye una etiqueta estable legible por máquinas y un mensaje legible por personas.

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:

```json theme={null}
{
  "_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](/es/developer-api/guides/receive-orders) 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](/es/developer-api/concepts/feedback) 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](/es/developer-api/guides/take-bookings).

`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](/es/developer-api/concepts/authentication).
* `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](/es/developer-api/concepts/idempotency), así que un reintento tras un tiempo de espera agotado no se aplicará dos veces.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.