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

# Errores

> Formato de error de la API, códigos y qué hacer con cada uno.

## Formato

Todos los errores de la API pública tienen la misma forma:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "Request inválida",
    "details": [{ "field": "query.limit", "message": "limit must be less than or equal to 100" }],
    "request_id": "0b6f6d3e-6c0e-4c0b-9a5a-6a8f6d1c2a10"
  }
}
```

| Campo | Detalle |
| - | - |
| `code` | Código estable en texto. Programá contra este campo, no contra `message`. |
| `message` | Descripción para humanos. Puede cambiar. |
| `details` | Lista con información extra (siempre es un arreglo, puede estar vacío). Su forma depende del código. |
| `request_id` | Id del request. Es el mismo valor del header `X-Request-Id`. |

**Mandá siempre el `request_id` a soporte** cuando reportes un problema: nos permite encontrar el request exacto.

## Códigos

| Código | Status | Cuándo pasa | Qué hacer |
| - | - | - | - |
| `invalid_request` | 400 | El request está mal armado: JSON inválido, un campo o parámetro que no existe, un valor fuera de rango (por ejemplo `limit`), un cursor inválido o de otros filtros, un body de más de 1 MiB, o falta el `Idempotency-Key` donde es obligatorio. | Corregí el request. `details` trae `{ field, message }` por cada problema. No reintentes igual. |
| `invalid_token` | 401 | Falta el header `Authorization: Bearer`, el access token es inválido o venció, la instalación ya no está activa (desinstalada o revocada), o la app no está disponible para esa tienda. | Renová el access token con el refresh token. Si el refresh también falla, la tienda tiene que volver a autorizar la app. |
| `insufficient_scope` | 403 | La instalación no tiene el scope que pide el endpoint. `details` trae `{ "required_scope": "..." }`. | Pedí el scope en el portal y pedile al comerciante que vuelva a autorizar (ver [Scopes y permisos](/scopes)). |
| `plan_required` | 403 | El plan actual del comercio no incluye apps, o llegó a un tope de su plan (por ejemplo la cantidad de productos). | Si el comercio bajó de plan, **la instalación sigue**, pero la API y los webhooks no obligatorios quedan pausados hasta que vuelva a un plan que incluya apps. Avisale al comerciante. |
| `account_suspended` | 403 | La cuenta del comercio está suspendida o con el medio de pago pendiente. | No reintentes. La operatoria vuelve cuando el comercio regulariza su cuenta. |
| `not_found` | 404 | El recurso no existe, **o pertenece a otro comercio** (nunca confirmamos que existe), o la ruta o la versión de la API no existe. | Revisá el id y la URL. Un id de otro comercio es indistinguible de uno inexistente. |
| `conflict` | 409 | El request choca con el estado actual: un request con el mismo `Idempotency-Key` todavía en curso, o una regla de negocio (por ejemplo una entrega que exige confirmar el cobro). `details[0].reason` indica el motivo. | Leé `details`, resolvé el conflicto y reintentá. Si es un `Idempotency-Key` en curso, esperá unos segundos y reenviá lo mismo. |
| `idempotency_conflict` | 422 | Reusaste un `Idempotency-Key` con un body distinto al del primer request. | Generá una clave nueva para cada operación distinta. |
| `rate_limited` | 429 | Superaste el límite de requests de tu app para esa tienda. | Esperá lo que indica el header `Retry-After` y reintentá con backoff (ver [Límites de uso](/rate-limits)). |
| `internal_error` | 500 | Falló algo de nuestro lado. | Reintentá con backoff exponencial. Si persiste, escribinos con el `request_id`. |

## Reintentos

Reintentá sólo lo que tiene sentido:

* **Sí**: `429` (respetando `Retry-After`), `500`, y `409` por idempotencia en curso.
* **Sí, después de renovar el token**: `401 invalid_token`.
* **No**: `400`, `403`, `404`, `422`. Repetir el mismo request da el mismo error.

Para las escrituras, mandá un `Idempotency-Key` y reintentá con la misma clave: si el primer intento sí llegó a aplicarse, el reintento devuelve la respuesta original en lugar de repetir la operación (ver [Idempotencia](/api#idempotencia)).

## Errores del endpoint de token

Los endpoints de OAuth (`/oauth/apps/token` y `/oauth/apps/revoke`) **no** usan este formato. Siguen el RFC 6749:

```json theme={null}
{ "error": "invalid_grant" }
```

Los códigos son `invalid_request`, `invalid_client`, `invalid_grant`, `unsupported_grant_type` y `server_error`. Los detalles están en [Autenticación OAuth](/oauth#errores-del-endpoint-de-token).


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