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).

Falhas de job (assíncronas)

Os erros acima são da requisição (chegam no HTTP do POST /generations). Um job aceito pode ainda falhar durante o processamento — nesse caso ele volta com status: "failed" e um error.code estável, um destes:

code	O que aconteceu
`insufficient_credits`	Saldo insuficiente para cobrir o job.
`content_policy_violation`	Prompt ou mídia recusados por política de conteúdo.
`generation_timeout`	O job excedeu o tempo máximo de processamento.
`rate_limited`	Limite de requisições por minuto excedido durante o processamento.
`invalid_input`	Parâmetro obrigatório ausente ou fora do schema do modelo.
`generation_failed`	Falha genérica no processamento do job.

São os mesmos códigos listados em cada página de modelo. Ramifique pelo code, nunca pela message.

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 } }