Erros de API — O que cada código significa e como corrigir

O FastOG retorna códigos de erro legíveis por máquina quando uma requisição falha — uma renderização de imagem OG assinada, ou uma chamada a uma das superfícies administrativas do produto. Toda resposta de erro inclui:

• error — o token curto legado. Ainda presente em toda falha para que um cliente mais antigo continue funcionando.
• code — o mesmo código de erro estável e documentado (tabela abaixo), sob o nome que a API pública usa.
• message — uma descrição em uma frase do que deu errado.
• hint — uma descrição curta em linguagem simples do que deu errado e como corrigir.
• docs_url — um link para esta página, ancorado na seção daquele código.
• request_id — correlaciona esta falha HTTP a uma linha na tabela Render Logs do dashboard (também retornado no cabeçalho de resposta X-Request-ID). Uma superfície sem nada a 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, então uma falha significa a mesma coisa onde quer que você a encontre. Uma superfície de módulo pode manter o status HTTP que sempre retornou 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 o link da documentação não mudam.

Lendo 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 você receber uma resposta que não entende, o caminho mais rápido é:

1. Anote o code.
2. Verifique seu construtor de URL — a maioria das falhas são bugs de assinatura, não problemas de conta.
3. Confira 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 solicitados para você reproduzir (e confirmar que request_id corresponde).

Assinatura e autenticação

missing_signature

Sua requisição está sem os parâmetros de consulta key e/ou s (assinatura).

Correção: garanta que sua URL inclua tanto key=<api-key> quanto s=<hmac-signature>. Use o SDK ou o passo a passo do /docs/hmac-signature-guide para montá-la.

invalid_signature

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

Correção: a assinatura cobre todos os parâmetros de consulta, exceto s, com as chaves ordenadas. Alterar qualquer parâmetro — incluindo reordenação, diferenças de codificação de URL ou adição de espaços em branco — invalida a assinatura. Reassine após cada alteração. Confirme que seu segredo é o mesmo exibido 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 deve ser o hex bruto do SHA-256 (a-f0-9 em minúsculas). Se você está codificando em base64 ou truncando a saída, use hex simples.

expired_timestamp

O timestamp t que você forneceu tem mais de 5 minutos.

Correção: gere o timestamp novamente a cada vez que montar uma URL. Este código se aplica ao fluxo legado de URL assinada; o fluxo atual HMAC v2 não tem timestamp.

invalid_api_key

A key que você passou não existe.

Correção: copie a chave de API completa do dashboard — é o identificador público que começa com sk_. Ela é pública e segura em URLs; o segredo (nunca em URLs) é o que comprova 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 exibido uma única vez na criação.

Parâmetro / entrada

invalid_image_url

Uma prop que contém uma URL (image, brand_logo, logo, avatar, background_image, ...) não é uma URL http(s) pública.

Correção: passe uma URL https://... acessível publicamente. Localhost, IPs privados e caminhos sem host são rejeitados para evitar server-side request forgery.

Assinatura

subscription_required (402)

A requisição chegou à Dynamic API, mas sua conta não tem um plano ativo. O acesso à API é exclusivo para assinantes: o plano é o pré-requisito, e ele traz a mesma cobertura + escada de recursos que os apps FastOG vendem. As renderizações em si não são medidas — não há cota mensal de renderizações nem cobrança por excedente.

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

Serviço de renderização

store_blocked (403)

A renderização da loja associada a esta chave foi pausada pelo FastOG (por exemplo, abuso ou uso descontrolado). As capas já armazenadas em cache na borda podem continuar sendo servidas até expirarem. Entre em contato com o suporte para resolver isso; nada que você altere na requisição vai corrigir isso.

render_unreachable

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

Correção: tente novamente em alguns segundos. A renderização não foi contabilizada para esta tentativa.

render_failed

O serviço de renderização retornou um erro para a sua requisição.

Correção: verifique as props do seu 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.

Interfaces de administração da loja

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

Ponte do Wix

A ponte do Wix é assinada pelo app do Wix, não por uma sessão de comerciante, portanto as falhas dela são direcionadas ao desenvolvedor do app. Toda resposta ainda carrega code e request_id; o id da requisição da ponte é o do envelope assinado.

Superfície de demonstração

A demonstração é o console de vendas exclusivo do proprietário, não um endpoint de merchant.

Códigos do editor de regras com escopo

Os editores de regras com escopo (Shopify admin e WooCommerce Studio) traduzem esses tokens por conta própria, para o idioma do próprio comerciante, então as respostas deles carregam error e code, mas não hint — uma segunda descrição em inglês só divergiria da versão localizada que o comerciante realmente vê:

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 problemas?

• Abra a página Render Logs do dashboard — cada resultado (sucesso + rejeição) é listado com seu error_code, status HTTP e os parâmetros solicitados.
• Execute php artisan og:diagnose em uma URL assinada para percorrer todo o pipeline e ver qual etapa falha.
• Consulte a documentação na barra lateral referente ao framework que você está usando (Next.js, Express, SvelteKit, ...).