Errores

Los errores siguen el estándar Problem Details (RFC 9457): un cuerpo application/problem+json con un code estable para que tu código distinga cada caso sin leer el texto.

Formato

Campo	Descripción
`type`	URL de la explicación de este error (esta página).
`title`	Nombre del código HTTP.
`status`	Código HTTP.
`detail`	Explicación para personas (en inglés). No la compares en tu código: usa `code`.
`code`	Código del error, estable entre versiones.
`errors`	Solo en `validation_error`: lista de `{field, code, message}` por campo.

Respuesta · 404

{
  "type": "https://creavibe.app/desarrolladores/api/errores/#not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Not found.",
  "code": "not_found"
}

Respuesta · 422 (validación)

{
  "type": "https://creavibe.app/desarrolladores/api/errores/#validation_error",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Some fields are not valid.",
  "code": "validation_error",
  "errors": [
    {
      "field": "input.prompt",
      "code": "string_too_short",
      "message": "String should have at least 1 character"
    }
  ]
}

Códigos de error

`code`	HTTP	Cuándo
`invalid_token`	`401`	El token no es válido, está revocado o ha caducado.
`authentication_required`	`401`	Falta el token.
`insufficient_credits`	`402`	No quedan créditos suficientes. Nada se ha cobrado.
`token_not_allowed`	`403`	La operación no está disponible con un token de API.
`permission_denied`	`403`	No tienes permiso sobre ese recurso.
`not_found`	`404`	No existe o no es tuyo.
`job_in_progress`	`409`	Ya hay un trabajo en marcha sobre esa imagen.
`idempotency_key_in_use`	`409`	Una petición con la misma clave aún se está procesando.
`precondition_failed`	`412`	El proyecto cambió: vuelve a obtenerlo.
`file_too_large`	`413`	El archivo es demasiado grande.
`page_too_large`	`413`	La página supera los 2 MB.
`validation_error`	`422`	Algún campo no es válido: mira `errors`.
`idempotency_key_reused`	`422`	La `Idempotency-Key` ya se usó con otra petición.
`page_count`	`422`	Un diseño tiene entre 1 y 3 páginas.
`embedded_image`	`422`	Hay una imagen incrustada (data:) de más de 100 KB: súbela a la biblioteca.
`template_not_found`	`422`	No existe esa plantilla (o no está publicada).
`asset_not_found`	`422`	No existe esa imagen en tu biblioteca.
`not_an_image`	`422`	La IA solo trabaja con imágenes (no SVG).
`style_not_found`	`422`	No existe ese estilo.
`library_full`	`422`	Tu biblioteca está llena (`limit_mb` indica su tamaño).
`invalid_webhook_url`	`422`	La `webhook_url` no es `https` o no es pública.
`rate_limited`	`429`	Has superado un límite de uso.
`internal_error`	`500`	Error inesperado en CreaVibe: vuelve a intentarlo en un momento.
`service_unavailable`	`503`	La IA (u otro servicio) no está disponible ahora.

Códigos de estado

Código	Significado	Cuándo
`200`	OK	La petición ha ido bien.
`201`	Creado	Se ha creado un recurso (un proyecto, un elemento de la biblioteca). La cabecera `Location` dice dónde está.
`202`	Aceptado	Se ha creado un trabajo de IA. La cabecera `Location` dice dónde consultarlo.
`204`	Sin contenido	Hecho, sin nada que devolver.
`401`	No autenticado	Falta el token, no es válido o ha caducado.
`402`	Sin créditos	No quedan créditos para esa acción.
`403`	No permitido	La acción no está disponible con un token de API.
`404`	No encontrado	No existe o no pertenece a tu cuenta.
`409`	Conflicto	Ya hay un trabajo en marcha sobre esa imagen, o una petición con la misma `Idempotency-Key` sin terminar.
`412`	Precondición fallida	El proyecto cambió desde la versión de `If-Match`.
`413`	Demasiado grande	El archivo o la página superan el tamaño máximo.
`422`	No válido	Falta un campo, tiene un valor no admitido o la `Idempotency-Key` se reutilizó con otros datos.
`429`	Demasiadas peticiones	Has superado un límite de uso. Espera lo que diga `Retry-After`.
`500`	Error interno	Algo falló en CreaVibe; ya está registrado.
`503`	No disponible	El servicio (la IA, los pagos) no está disponible en este momento.

Ejemplos

Respuesta · 401

{
  "type": "https://creavibe.app/desarrolladores/api/errores/#invalid_token",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The token is not valid or has expired. Create another one in your CreaVibe profile.",
  "code": "invalid_token"
}

Respuesta · 402

{
  "type": "https://creavibe.app/desarrolladores/api/errores/#insufficient_credits",
  "title": "Payment Required",
  "status": 402,
  "detail": "You have no AI credits left.",
  "code": "insufficient_credits"
}

Respuesta · 412

{
  "type": "https://creavibe.app/desarrolladores/api/errores/#precondition_failed",
  "title": "Precondition Failed",
  "status": 412,
  "detail": "The project changed since you loaded it. Load it again.",
  "code": "precondition_failed"
}

Respuesta · 422 (Idempotency-Key reutilizada)

{
  "type": "https://creavibe.app/desarrolladores/api/errores/#idempotency_key_reused",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "This Idempotency-Key was already used with a different request.",
  "code": "idempotency_key_reused"
}

Respuesta · 429

{
  "type": "https://creavibe.app/desarrolladores/api/errores/#rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Wait a moment and try again.",
  "code": "rate_limited"
}

Un trabajo de IA que falla no es un error de la petición: responde 200 con status: "failed" y su motivo en error.code (ver Trabajos de IA).