Errores

Última actualización: 2026-07-212 min de lectura

Los errores usan el formato RFC 7807 application/problem+json, de modo que son uniformes y legibles por máquina:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/validation",
  "title": "validation",
  "status": 400,
  "detail": "totalArea (m2) is required",
  "requestId": "req_…"
}

Registre siempre el requestId: cítelo en las peticiones al soporte para poder rastrear una llamada.

Códigos de estado

Estado	Significado	Qué hacer
`400`	Error de validación	Corrija el cuerpo o los parámetros según `detail`.
`401`	Clave inválida o ausente	Revise la cabecera `Authorization`.
`402`	Fondos o cuota insuficientes	Recargue o suba de plan.
`403`	Falta el alcance	La clave no está habilitada para esta herramienta.
`404`	No encontrado	Ruta incorrecta, o el recurso no existe.
`409`	Conflicto de idempotencia	Una petición con ese `Idempotency-Key` sigue en curso.
`422`	Regla de negocio	La petición es válida pero no se puede procesar tal cual.
`429`	Límite de frecuencia	Espere y reintente: véase Límites de frecuencia.
`5xx`	Error del servicio	Transitorio; reintente con espera creciente.

Una petición rechazada (4xx) no se cobra: el cargo por llamada solo se aplica en caso de éxito.

Cómo tratar los errores

Ramifique según el status HTTP numérico, no según el texto legible de detail.
Reintente 429 y 5xx con espera exponencial; no reintente los 4xx (salvo 409, cuando termine la petición en curso).
Los detalles de los proveedores nunca se filtran en los errores: un fallo aparece como un provider_error genérico.

¿Le resultó útil este artículo?