orkasa
ENEntrar

Conceptos

Errores

El envoltorio de error, los códigos estables, y qué hacer con cada uno.

Todo error sale con la misma forma:

{
  "error": {
    "code": "validation_error",
    "message": "…",
    "details": []
  }
}

code es el contrato. Ramifica sobre él, nunca sobre el estado HTTP ni sobre el mensaje: el mensaje está escrito para una persona y puede cambiar de redacción sin previo aviso.

codeHTTPcuándo
unauthorized401credencial ausente, mal formada, desconocida o revocada
forbidden403la credencial no tiene el permiso necesario
not_found404no existe esa fila en esta agencia
validation_error422cuerpo inválido, campo desconocido, transición ilegal
rate_limited429por encima del presupuesto de la credencial
internal_error500fallo inesperado (no se devuelven detalles)

404 en vez de 403, a propósito

Un identificador que existe en otra agencia se responde 404 not_found, nunca 403. Un 403 confirmaría que esa fila existe en algún sitio, y eso ya es información: se puede recorrer un espacio de identificadores y aprender el tamaño de la cartera del vecino. La API no confirma nada que esté fuera de tu agencia.

Los cuerpos son estrictos

Un campo que la API no conoce es un 422, no un campo ignorado en silencio. Un budget_maxx mal escrito falla en el momento, en vez de guardarse a medias y descubrirse tres semanas después cuando alguien nota que el embudo no cuadra.

Las columnas de sistema — brokerage_id, id, las marcas de tiempo, public_slug — no se alcanzan desde ningún cuerpo.

Cuando la etapa está bloqueada

Es el 422 más frecuente, y el que más información trae:

{
  "error": {
    "code": "validation_error",
    "message": "La etapa actual tiene 4 paso(s) pendiente(s).",
    "details": {
      "reason": "stage_gate_blocked",
      "pending_actions": [
        { "id": "ofertaPreparada", "label": "Oferta preparada con el comprador" },
        { "id": "ofertaEnviada",   "label": "Oferta enviada al vendedor" },
        { "id": "respuestaVendedor", "label": "Respuesta del vendedor recibida" },
        { "id": "precioAcordado",  "label": "Precio acordado" }
      ]
    }
  }
}

Nada se escribió. La transición se valida antes de tocar la fila, así que un rechazo deja la operación exactamente donde estaba. Ver Etapas.

En MCP los errores tienen dos niveles

El conector distingue dos cosas que no significan lo mismo:

  • error JSON-RPC — la trama no tiene sentido: método desconocido, params mal formados. Es un fallo de protocolo.
  • isError: true dentro del resultado — la llamada funcionó y la respuesta es « no, y por esto »: un expediente que no existe, una compuerta de etapa, un permiso no concedido.

La segunda forma es deliberada: el que llama es un modelo de lenguaje, y un código de protocolo le esconde la razón. Diciéndosela, puede contarle al agente qué falta en vez de reintentar lo mismo.