Erros de API — O que significa cada código e como corrigi-lo

O FastOG devolve códigos de erro legíveis por máquina quando um pedido falha — uma renderização de imagem OG assinada, ou uma chamada a uma das superfícies de administração do produto. Todas as respostas de erro incluem:

• error — o token curto legado. Continua presente em todas as falhas para que um cliente mais antigo continue a funcionar.
• code — o mesmo código de erro estável e documentado (tabela abaixo), sob o nome que a API pública utiliza.
• message — uma descrição numa frase do que correu mal.
• hint — uma descrição curta em linguagem simples do que correu mal e de como corrigi-lo.
• docs_url — uma ligação para esta página, ancorada na secção desse código.
• request_id — correlaciona esta falha HTTP com uma linha da tabela Render Logs do dashboard (também devolvido no cabeçalho de resposta X-Request-ID). Uma superfície sem nada para correlacionar responde null, mas a chave está sempre presente.

As superfícies do produto — o admin do Shopify, o WooCommerce Studio, a ponte do Wix e a demo — respondem com o mesmo envelope para os códigos abaixo, pelo que uma falha significa o mesmo onde quer que a encontre. Uma superfície de módulo pode manter o estado HTTP que sempre devolveu para um código (por exemplo, render_failed responde 503 na exportação de capa e 502 na API pública); o código, a mensagem, a dica e a ligação à documentação não mudam.

Ler uma resposta de erro

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

Se receber uma resposta que não compreende, o caminho mais rápido é:

1. Anote o code.
2. Verifique o seu construtor de URL — a maioria das falhas são bugs de assinatura, não problemas de conta.
3. Consulte o código abaixo para identificar a causa exata e a correção.
4. No dashboard, abra Render Logs e filtre pelo mesmo error_code — cada linha mostra os parâmetros pedidos para que possa reproduzir (e confirmar que request_id corresponde).

Assinatura e autenticação

missing_signature

Faltam na sua requisição os parâmetros de query key e/ou s (assinatura).

Correção: garanta que o seu URL inclui tanto key=<api-key> como s=<hmac-signature>. Use o SDK ou o guia /docs/hmac-signature-guide para o construir.

invalid_signature

O valor de s não corresponde ao que o seu segredo HMAC produz para este URL.

Correção: a assinatura cobre todos os parâmetros de query exceto s, com as chaves ordenadas. Alterar qualquer parâmetro — incluindo reordenar, diferenças de codificação de URL ou adicionar espaços — invalida a assinatura. Volte a assinar após cada alteração. Confirme que o seu segredo é o mesmo que foi mostrado quando a chave de API foi criada.

invalid_signature_format

O valor de s não é uma string hexadecimal de 64 caracteres.

Correção: a assinatura tem de ser SHA-256 hex em bruto (a-f0-9 minúsculo). Se estiver a codificar em base64 ou a truncar o resultado, use hex simples.

expired_timestamp

O timestamp t que forneceu tem mais de 5 minutos.

Correção: regenere o timestamp sempre que construir um URL. Este código aplica-se ao fluxo legado de URL assinado; o fluxo atual HMAC v2 não tem timestamp.

invalid_api_key

O key que passou não existe.

Correção: copie a chave de API completa a partir do dashboard — é o identificador público que começa por sk_. É público e seguro em URLs; o segredo (nunca em URLs) é o que prova a posse.

missing_hmac_secret

A chave de API não tem segredo HMAC configurado.

Correção: crie uma nova chave de API no dashboard — o segredo HMAC é gerado e mostrado uma única vez na criação.

Parâmetro / entrada

invalid_image_url

Uma prop com URL (image, brand_logo, logo, avatar, background_image, ...) não é um URL http(s) público.

Correção: passa um URL https://... acessível publicamente. Localhost, IPs privados e caminhos simples são rejeitados para prevenir server-side request forgery.

Subscrição

subscription_required (402)

O pedido chegou à Dynamic API, mas a sua conta não tem um plano ativo. O acesso à API é exclusivo para subscritores: o plano é o requisito de acesso e inclui a mesma cobertura e a mesma escala de capacidades que as aplicações FastOG comercializam. As renderizações em si não são contabilizadas — não existe quota mensal de renderizações nem faturação de excesso.

Correção: escolha um plano da Dynamic API no dashboard e crie uma chave de API. A resposta inclui um top_up_url que aponta para a página dos planos.

Serviço de renderização

store_blocked (403)

A renderização para a loja associada a esta chave foi suspensa pela FastOG (por exemplo, abuso ou utilização descontrolada). As capas já em cache no edge podem continuar a ser servidas até expirarem. Contacta o suporte para resolver a situação; nada que possas alterar no pedido irá corrigir isto.

render_unreachable

Não foi possível contactar o serviço de renderização (janela breve de reinício).

Correção: tenta novamente dentro de alguns segundos. A renderização não foi contabilizada para esta tentativa.

render_failed

O serviço de renderização devolveu um erro para o teu pedido.

Correção: verifica as props do teu template — valores longos/malformados, campos não suportados ou uma imagem upstream inacessível. A resposta inclui o status subjacente. A renderização não foi contabilizada.

Superfícies de administração da loja

Estes códigos respondem a partir do admin do Shopify e do WooCommerce Studio — os editores incorporados em que o comerciante trabalha, em vez da API assinada. Vários são partilhados com a API pública (invalid_image_url, render_failed, invalid_signature); esses mantêm a entrada documentada acima.

Bridge do Wix

O bridge do Wix é assinado pela app Wix, não por uma sessão de comerciante, pelo que as suas falhas se dirigem ao programador da app. Todas as respostas continuam a incluir code e request_id; o id do pedido do bridge é o do envelope assinado.

Superfície de demonstração

A demonstração é a consola de vendas exclusiva do proprietário, não um endpoint de comerciante.

Códigos do editor de regras com âmbito

Os editores de regras com âmbito (administração do Shopify e WooCommerce Studio) traduzem estes tokens para o idioma do próprio comerciante, pelo que as suas respostas incluem error e code mas não hint — uma segunda descrição em inglês apenas divergiria da versão localizada que o comerciante vê efetivamente:

scope_already_defined, scoped_rule_limit_reached, scoped_rules_not_on_plan, scope_value_required, scope_value_too_long, unknown_scope_type, base_rule_required, scoped_rules_product_only, cannot_delete_base_rule.

Ainda com dificuldades?

• Abra a página Render Logs do dashboard — cada resultado (sucesso + rejeição) é listado com o respetivo error_code, o estado HTTP e os parâmetros pedidos.
• Execute php artisan og:diagnose num URL assinado para percorrer todo o pipeline e ver em que etapa falha.
• Consulte a documentação na barra lateral para o framework que está a usar (Next.js, Express, SvelteKit, ...).