Referência

Erros e limites

Códigos de estado HTTP, formato de erros, limites de créditos e comportamento de timeouts em todos os endpoints da API Pedra.

Formato de resposta de erro

Pedidos falhados devolvem um estado HTTP não-200 com um corpo JSON contendo um campo error que descreve o que correu mal.

JSON
{
  "error": "User not found"
}

Códigos de estado

A API Pedra usa um conjunto deliberadamente pequeno de códigos de estado. Não há 401, nem 429, nem 413 — erros de autenticação e quota devolvem 404 e 403 respetivamente, e hoje não há limites de débito do lado do servidor.

Estado
Significado
200
Sucesso. Os endpoints de imagem devolvem output (array ou objeto único — ver cada endpoint); o endpoint de vídeo devolve videoId e um videoUrl pronto para streaming.
400
Pedido inválido. Devolvido por /api/create_video para array images em falta, imageUrl em falta numa imagem, valor effect inválido ou effect: "transition" sem secondImageUrl.
403
Créditos insuficientes. O corpo do erro explica quantos créditos a chamada precisava vs. quantos restam. Recarrega em app.pedra.ai ou envia email para felix@pedra.ai.
404
{"error": "User not found"} — a chave API não correspondia a nenhuma conta. É a resposta para chaves em falta, inválidas ou revogadas.
405
Método não permitido. Todos os endpoints aceitam apenas POST.
500
Erro do servidor. Habitualmente expõe a exceção de processamento subjacente no campo error. Para o endpoint de vídeo, também devolvido no timeout interno de 10 minutos.

Erros comuns

User not found (404)

A chave API não correspondia a nenhuma conta Pedra. Verifica se a chave corresponde à que emitimos e se está no corpo JSON como apiKey — não como cabeçalho Authorization.

Insufficient credits (403)

Cada plano inclui uma alocação mensal de créditos — ver pedra.ai/pricing. Os endpoints de imagem custam 1 crédito; cada frame de vídeo não estático custa 5. Quando ficas sem créditos, recebes um 403 com o cálculo exato. Recarrega ou muda de plano em app.pedra.ai → Definições → Subscrição e créditos.

Invalid effect 'X' at index N (400)

O endpoint de vídeo valida effect contra o conjunto [zoom-in, zoom-out, transition, static]. A mensagem de erro indica o índice da imagem em falta.

Video processing timeout after 10 minutes (500)

O endpoint de vídeo bloqueia até 10 minutos durante a renderização. Se a renderização exceder essa janela, o endpoint devolve 500. O vídeo pode ainda terminar em segundo plano — envia email ao suporte com o corpo do pedido para obter o URL final.

Image fetch failed (500)

A Pedra não conseguiu descarregar o imageUrl em 20 segundos. Causas: URL com autenticação, URL pré-assinado expirado, origem lenta. Para URLs pré-assinados S3/R2/Cloudinary, envia a imagem como URI data base64 data:image — a Pedra usa os bytes diretamente.

Limites de débito

Hoje não há limites por segundo ou por minuto na API Pedra. O débito é limitado pelos teus créditos restantes e pela capacidade de processamento subjacente. Se vais executar batches de alto volume e precisas de um débito mínimo garantido, envia email para felix@pedra.ai.

Timeouts

  • Descarga de imagem: A Pedra desiste após 20 segundos a tentar descarregar o imageUrl.
  • Endpoints de imagem (enhance, furnish, empty_room, renovation, etc.): resposta típica 10–30 segundos.
  • Endpoint de vídeo: bloqueia até 10 minutos. Configura o timeout do cliente HTTP para pelo menos 11 minutos.

Repetir com segurança

Todos os endpoints são idempotentes dentro de um pedido — repetir com o mesmo corpo produz uma nova geração, nunca um estado corrompido. Pedidos falhados (4xx/5xx) não consomem créditos na maioria dos caminhos; a dedução de créditos acontece dentro do método Meteor assim que o processamento começa.

Precisas de ajuda?

Envia email para felix@pedra.ai com o corpo do pedido falhado e a resposta. Respondemos no prazo de um dia útil. Ver Preços para opções de créditos e quotas.