Conceitos

Erros & limites

Erros são JSON previsível. Cada job também reporta o quanto custou em credits_charged.

Formato do erro

Toda falha vem com success: false e um objeto error com code estável (para o seu código ramificar) e message legível:

json

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits."
  }
}

Códigos comuns

HTTP	code	O que aconteceu
401	`invalid_api_key`	Chave ausente, malformada, inválida ou revogada.
403	`api_disabled`	API desligada globalmente, ou sua conta não está no beta / sem plano ativo.
400	`invalid_request`	Parâmetros inválidos (campo faltando, valor fora do enum/range).
400	`insufficient_credits`	Saldo insuficiente para o job. Consulte `GET /balance` e recarregue.
404	`not_found`	Slug de modelo ou id de geração inexistente.
429	`rate_limit`	Limite de taxa estourado. Espere e tente de novo (backoff).

Limites de taxa

As gerações são limitadas a cerca de 20 por minuto por conta (uploads têm o mesmo teto). O restante da superfície /dev tem um limite global mais alto. Ao receber 429, aplique backoff exponencial antes de repetir.

Créditos

Cada geração debita créditos do saldo da conta. O custo é específico do modelo/tool e volta em credits_charged no job concluído. Acompanhe o saldo a qualquer momento:

bash

curl https://caranguejo.art/api/v1/dev/balance \
  -H "Authorization: Bearer $CK"

json

{ "data": { "credits": 4820 } }