---
title: "Respuestas y errores"
description: "El envoltorio de respuesta, el objeto de error y sus códigos, los ids de solicitud y los límites de tamaño."
---

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

# Respuestas y errores

Todas las operaciones responden JSON en el mismo envoltorio (envelope), tengan éxito o fallen, así que un mismo código puede leer cualquier respuesta. La única excepción son las [respuestas en texto para agentes de IA](#respuestas-en-texto-para-agentes-de-ia), que tú pides.

## El envoltorio

| Campo | Si tiene éxito | Si falla |
| --- | --- | --- |
| `success` | `true` | `false` |
| `data` | El resultado: un registro, una [página](/developers/concepts/pagination/) o lo que declare la operación. | `null` |
| `error` | `null` | El [objeto de error](#el-objeto-de-error). |
| `metadata` | `{ "requestId": "…" }` | `{ "requestId": "…" }` |

Un éxito, aquí de [`account.apiKeys.delete`](/api/account/api-keys/delete/):

```json
{
  "success": true,
  "data": { "id": "exampleClientId0001", "deleted": true },
  "error": null,
  "metadata": { "requestId": "00000000-0000-4000-8000-000000000001" }
}
```

El código de estado también distingue el éxito del fallo: los éxitos responden `200`, los fallos `4xx` o `5xx`. El SDK de TypeScript resuelve con el envoltorio completo y lanza `ApiError` con cualquier otro estado; el SDK de Rust devuelve `data`.

## El objeto de error

Un fallo, aquí una solicitud sin una credencial válida:

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid access token is required.",
    "retryable": false,
    "data": {}
  },
  "metadata": { "requestId": "00000000-0000-4000-8000-000000000002" }
}
```

| Campo | Significado |
| --- | --- |
| `code` | El código del fallo, estable entre versiones. Decide según él. |
| `message` | Qué salió mal, para personas. Nunca contiene valores de la entrada. No lo analices. |
| `retryable` | Si repetir la misma solicitud puede tener éxito. Consulta [Reintentos](/developers/concepts/retries/). |
| `data` | Diagnósticos que declara el código. Vacío en la mayoría de los códigos. |

Para `INVALID_INPUT`, `data.issues` lista hasta 10 problemas, cada uno con un `path`, que es un JSON Pointer [RFC 6901](https://www.rfc-editor.org/rfc/rfc6901) al campo rechazado (vacío para la entrada completa), y un `message`.

## Códigos comunes

Estos códigos pueden venir de cualquier servicio. La página de cada operación en la referencia de la API lista los códigos que responde, por estado.

| Estado | `code` | `retryable` | Significado |
| --- | --- | --- | --- |
| `400` | `INVALID_INPUT` | `false` | La solicitud no coincide con el esquema publicado. |
| `401` | `UNAUTHORIZED` | `false` | Se requiere un token de acceso válido. Consulta [401 o 403](/developers/authentication/#401-o-403). |
| `403` | `FORBIDDEN` | `false` | El token no autoriza esta operación. |
| `404` | `NOT_FOUND` | `false` | Nada coincide con la ruta. |
| `405` | `HTTP_METHOD_NOT_ALLOWED` | `false` | El método HTTP no se admite para este recurso. |
| `413` | `REQUEST_TOO_LARGE` | `false` | La solicitud supera el tamaño permitido. Consulta [Límites de tamaño](#límites-de-tamaño). |
| `415` | `UNSUPPORTED_MEDIA_TYPE` | `false` | El tipo de contenido de la solicitud no se admite. Envía los cuerpos JSON como `application/json`. |
| `429` | `RATE_LIMITED` | `true` | Se superó el límite de solicitudes. Espera los segundos de `Retry-After`. |
| `500` | `INTERNAL_ERROR` | `false` | El servicio no pudo completar la operación. |
| `502` | `OUTCOME_UNKNOWN` | `false` | Puede que la operación se haya aplicado. Revisa su resultado antes de repetirla. |
| `503` | `UPSTREAM_UNAVAILABLE` | `true` | El servicio de origen (upstream) no pudo completar la solicitud. |
| `504` | `UPSTREAM_TIMEOUT` | `true` | El servicio de origen no respondió antes de su plazo. |

Los servicios agregan sus propios códigos para sus propias reglas, como `API_KEY_NOT_FOUND` (`404`) en Cuenta o `VERSION_CONFLICT` (`409`) en Raíz.

## Ids de solicitud

Cada respuesta lleva un encabezado `X-Request-Id`, y el envoltorio lo repite como `metadata.requestId`. Regístralo con cada fallo e inclúyelo cuando reportes un problema.

Las respuestas a `429`, y a algunos otros fallos según lo indique su referencia, también llevan `Retry-After`: los segundos que hay que esperar antes de otro intento.

## Límites de tamaño

Cada operación acepta una solicitud y devuelve una respuesta de un tamaño máximo, que su página en la referencia de la API indica en **Limits**. Un cuerpo más grande se rechaza con `413 REQUEST_TOO_LARGE`; en [MCP](/developers/mcp/), el límite aplica a la entrada de la herramienta.

La mayoría de las operaciones aceptan un cuerpo de hasta 32 KiB. Las operaciones que llevan archivos aceptan más, como [`raiz.knowledge.create`](/api/raiz/knowledge/create/) (12 MiB) y [`raiz.contacts.import`](/api/raiz/contacts/import/) (16 MiB). Las respuestas van desde 256 KiB, como en [`account.organization.get`](/api/account/organization/get/), hasta 16 MiB en [`account.invoiceDocuments.get`](/api/account/invoice-documents/get/). El SDK de Rust trata como inválida una respuesta más grande que el límite de su operación.

En el documento OpenAPI de la API (`https://api.getarbol.com/v1/<service>/openapi.json`), cada operación lleva sus límites en bytes, en `x-max-body-bytes` y `x-max-output-bytes`.

## Respuestas en texto para agentes de IA

Algunas operaciones de integraciones, como las de SURA, Nueva EPS y ADRES, reciben un `agentMode` opcional. Con `agentMode: true` responden un texto breve en español, pensado para un agente de IA, con la misma autorización. Según la operación, el texto llega como `text/plain` en lugar de JSON, o dentro del envoltorio, en `data.text`; la página de cada operación en la referencia dice cuál. Omítelo para recibir el resultado estructurado.

Source: https://docs.getarbol.com/developers/concepts/responses-and-errors/index.mdx