Errores

Forma del error

El campo code es estable y no cambiará dentro de v1; message es copy para humanos y puede cambiar. Algunos errores añaden campos extra (p. ej. permission o issues).

{ "error": { "code": "…", "message": "…" } }

Códigos

• unauthorizedHTTP 401

  Key ausente, malformada, desconocida, revocada o caducada. La respuesta es idéntica en todos los casos: no se puede sondear si una key existió.

• missing_permissionHTTP 403

  La key es válida pero no tiene el permiso que exige el endpoint. El campo permission indica cuál falta.

• forbiddenHTTP 403

  Operación reservada (p. ej. moderar comentarios ajenos).

• not_foundHTTP 404

  El recurso no existe o pertenece a otro proyecto — indistinguibles a propósito.

• validation_errorHTTP 400

  Cuerpo o query inválidos. issues detalla campo a campo. Los cuerpos son estrictos: campos desconocidos también fallan.

• conflictHTTP 409

  Violación de unicidad (p. ej. etiqueta duplicada).

• dependency_cycleHTTP 409

  La dependencia dejaría a dos tareas esperándose entre sí. Es un error propio precisamente para no confundirlo con una falta de permisos.

• storage_unavailableHTTP 503

  El despliegue no tiene almacenamiento configurado, así que los adjuntos están desactivados. No es un fallo de tu petición.

• rate_limitedHTTP 429

  Límite superado. Respeta la cabecera Retry-After.

• internal_errorHTTP 500

  Error inesperado. Sin detalles internos, a propósito.

Errores de validación

Un cuerpo o unos parámetros inválidos responden 400 con el detalle campo a campo en issues. Recuerda que los cuerpos son estrictos: un campo desconocido también es un error de validación (ver Convenciones).

{
  "error": {
    "code": "validation_error",
    "message": "Petición no válida.",
    "issues": [{ "path": "title", "message": "El título es obligatorio." }]
  }
}