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 413 — uma chave API desconhecida devolve 404. Ficar sem créditos devolve 403 nos endpoints de imagem, vídeo e voz e 402 nos endpoints de tours virtuais. 429 só é usado para os limites diários de carregamento e o registo por agente — não há limites por segundo nem por minuto.

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. Os endpoints de imagem devolvem-no quando imageUrl não devolve uma imagem válida (resposta não-200, ou bytes que não são uma imagem descodificável). Também devolvido por /api/create_video para array images em falta, imageUrl em falta numa imagem, valor effect inválido ou effect: "transition" sem secondImageUrl.
402
Créditos insuficientes nos endpoints de tours virtuais (create_virtual_tour, add_virtual_tour_scenes). O corpo traz code: "insufficient_credits", creditsRequired, creditsAvailable e upgradeUrl. Nada é criado nem cobrado.
403
Créditos insuficientes nos endpoints de imagem, vídeo e voz. A mensagem de error 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.
429
Foi atingido um limite diário. code diz qual: upload_limit (limite diário de carregamento), upload_link_limit (links de carregamento por dia) ou rate_limited (registo por agente). Ver Limite diário de carregamento.
500
Erro do servidor. Habitualmente expõe a exceção de processamento subjacente no campo error.

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 / 402)

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 (um 402 com creditsRequired e creditsAvailable nos endpoints de tours virtuais). Recarrega ou muda de plano em app.pedra.ai → Definições → Subscrição e créditos.

JSON
{
  "error": "Insufficient credits. You need 5 credits but only have 2 remaining. Please purchase more credits at app.pedra.ai or contact felix@pedra.ai for support."
}

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.

imageUrl did not return a valid image (400)

O imageUrl não apontava para uma imagem utilizável. Ou o URL respondeu com um estado não-200 (frequentemente uma página de erro HTML 404 servida num URL .png), ou os bytes descarregados não eram uma imagem descodificável. Abre o URL numa janela de navegação privada para confirmar que devolve o ficheiro de imagem real — não uma página de login, erro ou marcador.

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

Na API Pedra não há limites por segundo nem por minuto. O débito é limitado pelos teus créditos restantes e pela capacidade de processamento subjacente. Os únicos limites são diários: nas fotos que entram de fora da app (abaixo), nos links de carregamento e no registo por agente. Se vais executar batches de alto volume e precisas de um débito mínimo garantido, envia email para felix@pedra.ai.

Limite diário de carregamento

Cada imagem guardada a partir de fora da app conta para uma quota diária por conta: 30 por dia no plano gratuito, 500 por dia nos planos pagos, reposta à meia-noite UTC. O que conta:

  • add_images_to_property (URLs e URIs data:)
  • Fotos 360° enviadas por URL a create_virtual_tour e add_virtual_tour_scenes
  • Ficheiros carregados através de um link de carregamento e fotos anexadas no ChatGPT que são adicionadas a um imóvel

As fotos que editas por imageUrl e as carregadas na app Pedra não contam. Acima do limite, a chamada devolve 429 com code: "upload_limit" e é recusada por inteiro — nada é guardado. Os itens que falham por si (um URL que não carrega, uma foto que não é 360°) não contam. Precisas de mais margem num plano pago? Envia email para felix@pedra.ai.

JSON
{
  "error": "Daily upload limit reached (30 images per day on this plan). It resets at midnight UTC. Paid plans have a higher limit: https://www.pedra.ai/pricing",
  "code": "upload_limit"
}

Dois limites diários relacionados: upload_link_limit — 5 links de carregamento por dia no plano gratuito, 50 nos planos pagos (cada link funciona 24 horas, por isso reutiliza-o); e rate_limited — pedidos de registo por agente por endereço de email e por IP.

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: síncrono — bloqueia enquanto o vídeo é renderizado, o que pode demorar vários minutos. Define o timeout do teu cliente HTTP de forma generosa.

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.