Errores

Sobre

Las respuestas exitosas devuelven { "data": … }. Las fallas devuelven un objeto error y un estado HTTP distinto de 2xx. Decide según el código de estado, no según una bandera en el cuerpo:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param",
    "message": "status must be one of TRACKING, NOT_TRACKING.",
    "param": "status",
    "details": {
      "issues": [{ "path": "status", "message": "status must be one of TRACKING, NOT_TRACKING." }]
    }
  }
}

Campo	Notas
`type`	Categoría amplia (ver abajo).
`code`	Código específico legible por máquina. Decide según este.
`message`	Legible para humanos; seguro de mostrar en la interfaz.
`param`	Campo que causó el error. Presente en errores de validación.
`details`	Detalle estructurado opcional (por ejemplo, todos los `issues` de validación).

Cada respuesta trae además un encabezado X-Request-Id; inclúyelo al reportar un problema. Las respuestas de error repiten el code en un encabezado X-Croma-Error-Code, para que puedas decidir sin parsear el cuerpo.

Tipos y códigos

Estado	`type`	`code`	Significado
`400`	`invalid_request_error`	`invalid_param`	Un parámetro de consulta o campo del cuerpo no pasó la validación; consulta `param` / `details`. Aquí caen los valores de enumerado desconocidos, una `city` no reconocida o un cuerpo de exportación inválido.
`400`	`invalid_request_error`	`callback_unavailable`	La entrega por callback de las exportaciones no está disponible por ahora. Espera en línea o consulta la URL de estado.
`401`	`authentication_error`	`invalid_api_key`	Clave faltante o inválida. Consulta Autenticación.
`401`	`authentication_error`	`personal_api_key_not_allowed`	Se usó una clave personal; solo claves de organización.
`404`	`not_found_error`	`not_found`	No hay un proceso con ese id o radicado en tu organización.
`404`	`not_found_error`	`job_not_found`	No hay un trabajo de exportación con ese id en tu organización.
`404`	`not_found_error`	`endpoint_not_found`	No hay un endpoint de la API en esa ruta. Consulta la Referencia de API.
`405`	`invalid_request_error`	`method_not_allowed`	Método incorrecto. Los endpoints de lectura son `GET`; las exportaciones son `POST`. El encabezado `Allow` indica el correcto.
`429`	`rate_limit_error`	`rate_limited`	Cuota excedida; consulta Límites de tasa.
`500`	`api_error`	`internal_error`	Error interno inesperado. Reintenta y, si persiste, contacta a soporte con el `X-Request-Id`.
`502`	`api_error`	`job_failed`	Una exportación esperada en línea falló.

Una lista “sin coincidencias” nunca es un 404: las búsquedas y los feeds devuelven 200 con data vacío, y un demandado sin procesos devuelve una lista vacía. Solo los endpoints de un proceso individual (GET /v1/processes/{id} y su /actions) devuelven 404, y solo cuando el id o radicado no está en tu organización. Un proceso que existe pero pertenece a otra organización también se lee como 404.

Las exportaciones también pueden fallar como trabajo en lugar de como error HTTP: un trabajo consultado por polling o recibido por callback trae el mismo objeto error dentro del sobre, con code: "job_failed".

Primeros pasos

Guías

Referencia de API

Sobre

Tipos y códigos

​Sobre

​Tipos y códigos

Sobre

Tipos y códigos