Formato de error y códigos de error de la API

Todas las respuestas de error de la API tienen el mismo formato. Tu código debe basarse en el código de error del campo error, no en el texto de message: el código se mantiene estable, mientras que el texto puede cambiar y se traduce al idioma de la cuenta.

#Estructura de una respuesta de error

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Código legible por máquinas, por ejemplo not_found. En la mayoría de los errores también aparece en el encabezado X-Error-Code, pero básate en el campo del cuerpo.

message

Descripción legible para personas en el idioma de la cuenta: con una clave de API, el del propietario del espacio de trabajo; con una app conectada, el de la persona que la conectó. Sin un token válido (por ejemplo, el 401 de la comprobación del token), el idioma sigue a Accept-Language; si no, es inglés. El encabezado Content-Language indica el idioma.

details

Solo aparece cuando hay algo más que decir. Para un 422 de la validación de la entrada, una lista con field, reason y message para cada problema; para un 422 de la lógica de negocio y todos los demás errores, un objeto, por ejemplo con reason, retry_after_sec o una lista de issues. Cuando se supera un tamaño contiene field, reason y limit, y en 413 request_too_large, max_bytes y max_kb. Así que comprueba si details es una lista.

request_id

El ID de la petición. También está en el encabezado X-Request-Id. Inclúyelo cuando contactes con soporte.

Excepciones: la respuesta 429 rate_limited tiene el campo retry_after_sec en lugar de details; con 429 y con 403 insufficient_scope, falta request_id en el cuerpo. El 401 de la comprobación del token y el 422 de la comprobación del esquema no llevan el encabezado X-Error-Code; en la comprobación del esquema solo se traduce el message principal, los textos de details siguen en inglés. El encabezado X-Request-Id siempre está presente.

#Los códigos más importantes

#Leer los errores de entrada

Con 422 validation_failed, details enumera cada problema por separado: field es la ruta del campo (con barras para los objetos anidados, por ejemplo theme_config/button_style) y reason es la regla incumplida, como required, minLength, maxLength, enum o additionalProperties. Con additionalProperties, el mensaje dice qué campos son desconocidos; a menudo es una errata en el nombre del campo.

#Gestión recomendada en tu código

• 400, 413 y 422: no repitas la petición; corrígela
• 401 invalid_token: pide un token nuevo una vez y repite la petición
• 403: no repitas la petición; revisa el scope, el plan o quién puede hacer esto
• 404: revisa el ID; después de una eliminación es lo normal
• 409: vuelve a cargar el estado y decide si la acción sigue haciendo falta
• 429: espera lo que indique Retry-After y repite la petición; consulta Límites de peticiones
• 500 y 503: repite unas pocas veces con pausas cada vez más largas