Errores

Los errores llegan siempre como RFC 9457 application/problem+json:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/business_rule",
  "title": "business_rule",
  "status": 422,
  "detail": "Describe the property: pick a listing or fill in at least a description, city or area",
  "code": "not_enough_input",
  "requestId": "req_..."
}

Un error de validación con campos:

{
  "title": "validation",
  "status": 400,
  "detail": "\"avatarId\" is required",
  "errors": [{ "field": "avatarId", "message": "\"avatarId\" is required" }],
  "requestId": "req_..."
}

Códigos de error

La URL de type lleva a la entrada correspondiente de esta lista.

invalid_key

401. La clave falta, es errónea, está revocada o ha caducado. Revise el encabezado Authorization y el estado de la clave en el panel.

forbidden_scope

403. La clave es válida pero le falta el ámbito necesario. Añada el ámbito o cree una clave nueva (Autenticación).

forbidden

403. La acción no está permitida para esta cuenta o recurso: por ejemplo, el inmueble pertenece a otra cuenta o el rol en la agencia es insuficiente. El motivo está en detail.

insufficient_funds

402. No hay saldo suficiente en el monedero, la cuota del plan se ha agotado, hay una deuda pendiente o se alcanzó el límite de uso razonable. code indica cuál: INSUFFICIENT_FUNDS, QUOTA_EXCEEDED, DEBT_OUTSTANDING, FAIR_USE_LIMIT_REACHED, etc. Recargue, pague la deuda o cambie de plan.

validation

400. La solicitud no superó la validación. Qué falla exactamente está en detail y errors. Corrija la solicitud; repetirla sin cambios no sirve.

business_rule

422. La solicitud está bien formada pero no puede ejecutarse: faltan datos, el inmueble está en un estado inadecuado, el tipo de inmueble no se admite, etc. El motivo está en detail, el código máquina en code.

payload_too_large

413. El cuerpo o un archivo supera el límite. Los límites de tamaño se indican en cada herramienta. Un cuerpo que no es JSON válido es 400 validation.

range_not_satisfiable

416. El Range de una descarga queda fuera del archivo. Content-Range: bytes */size indica el tamaño del archivo.

rate_limited

429. Límite de frecuencia superado. Espere los segundos que indique Retry-After y repita (Límites y cobro). code indica qué límite: minute_limit (segundos) o daily_limit (se reinicia a las 00:00 UTC).

not_found

404. Ruta desconocida, o un recurso que no existe o no es suyo. Un recurso ajeno recibe a propósito la misma respuesta que uno inexistente.

idempotency_conflict

409. Una solicitud con este Idempotency-Key aún se está ejecutando. Espere a que termine y repita con la misma clave (Idempotencia). Tras un tiempo de espera agotado (502 provider_error) la clave queda retenida 15 minutos: compruebe el resultado antes de repetir; una repetición después de la retención vuelve a ejecutar el trabajo de pago. La valoración exprés libera la clave tras el tiempo agotado: repítala con la misma clave. El mismo 409 llega cuando el pago de una llamada con esta clave aún se está reservando (code RESERVE_IN_PROGRESS, RESERVE_BUSY): repita más tarde; RESERVE_REF_TAKEN: la clave está agotada, envíe una nueva.

conflict

409. El recurso está en un estado que no permite esta acción (por ejemplo, mover un inmueble de una agencia a otra, borrar un inmueble con un contrato de comisión vigente). El motivo está en detail. No repita la solicitud sin cambios.

service_unavailable

503. La herramienta no está disponible temporalmente. No se ha cobrado nada. Repita tras la pausa de Retry-After; GET /tools/status muestra el estado actual de las herramientas.

provider_error

502. Falló el servicio que hace el trabajo. Es temporal: repita con una pausa creciente. Si detail dice que la herramienta no respondió a tiempo, el trabajo aún puede terminar y cobrarse: revise GET /works antes de lanzarlo de nuevo; la valoración exprés repítala con el mismo Idempotency-Key. Los resultados de la mejora de fotos, del sitio y del borrador no se guardan en GET /works: para ellos espere a que acabe la retención de 15 minutos y compruebe el resultado en el panel o entre sus inmuebles.

internal_error

500. Error interno. Repita con una pausa; si persiste, contacte con soporte indicando el requestId.

La lista puede crecer. Trate un código desconocido como un error genérico de su clase HTTP (4xx, problema de la solicitud; 5xx, fallo del servicio).

Qué repetir

Al repetir solicitudes que crean algo, envíe siempre el mismo Idempotency-Key: así la repetición no ejecutará ni cobrará el trabajo dos veces.

Excepciones

• Los eventos de Swipe Match (POST /match/leads/{id}/events) no permitidos por el estado actual del lead responden 409 con title: business_rule y el motivo en code (client_event_rejected, invalid_transition, not_available).
• Las acciones del pool de leads de la agencia (POST /leads/{id}/claim, POST /leads/{id}/return-to-pool) con una clave personal o un rol insuficiente responden 403 con title: forbidden.

Qué no se cobra

Una solicitud rechazada (cualquier respuesta 4xx o 5xx) no consume una llamada a la API. El precio de la herramienta se cobra solo por trabajo aceptado. La excepción es provider_error tras un tiempo de espera agotado: el trabajo puede terminar y cobrarse; compruebe GET /works antes de lanzarlo de nuevo (mejora de fotos, sitio y borrador: en el panel o entre sus inmuebles).

Artículos relacionados

• Límites y cobro
• Idempotencia
• Autenticación