Códigos de erro

Códigos de status HTTP da Listings API, códigos de erro SYxxxxx para Listings e Social e os três formatos de resposta de erro que a API v4 retorna.

A Listings API usa códigos de status HTTP convencionais para informar o resultado de uma requisição. Os códigos de erro têm o prefixo SY e são enviados na string message do erro, no formato SYxxxxx: <human-readable reason>.

Códigos de status HTTP

Três formatos de resposta

A maioria das falhas contém um array errors, no nível superior ou aninhado no resultado da operação, como mostram as seções abaixo. Algumas falhas retornam um único objeto error em vez disso: limitação de taxa (429) e algumas falhas no nível da requisição (400/500 com um code como INTERNAL_SERVER_ERROR). Verifique ambos: errors é um array, error é um objeto.

1. No nível da requisição: errors[] no nível superior

Falhas de autenticação, autorização e requisições malformadas interrompem o processamento antes que a operação seja executada. Elas retornam o status 4xx correspondente (acima) com o erro no nível superior da resposta.

{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. Validação de escrita: data.<operation>.errors[] aninhado

Uma requisição de criação, atualização ou publicação que esteja bem formada nos demais aspectos retorna HTTP 200. Se a entrada violar uma regra de negócio, a falha será informada de forma aninhada no payload da própria operação, em data.<operation>.errors. Em caso de sucesso, esse array está presente e vazio ("errors": []).

{  "data": {    "createLocation": {      "errors": [        { "message": "SY10126: City is Mandatory" },        { "message": "SY10010: state_iso" }      ],      "location": null    }  }}

3. No nível do gateway: um único objeto error no nível superior

A limitação de taxa e as falhas inesperadas do gateway interrompem o processamento antes da tradução e retornam um objeto error com um code, um message e um correlation_id. Consulte rate_limited abaixo para ver o corpo da resposta 429.

Sempre leia data.<operation>.errors em uma operação de escrita, mesmo em uma resposta 200 com um objeto data.<operation> preenchido: uma operação de escrita pode falhar parcialmente e informar a falha aqui.

Uma resposta 402 Payment Required não tem um invólucro error: code, message, doc_url e, quando há uma fatura a pagar, pay_url ficam no nível superior. Consulte payment_required abaixo.

Repetir uma operação de escrita tem consequências

A API v4 não oferece suporte a Idempotency-Key: o cabeçalho é ignorado e nenhum endpoint detecta operações de escrita repetidas. Uma chamada de criação, atualização ou publicação que exceda o tempo limite ou retorne um 5xx ainda pode ter sido efetivada no servidor, portanto, uma nova tentativa sem verificação pode gerar um local, uma publicação ou uma resposta a uma avaliação em duplicidade.

Repita as leituras livremente, com intervalos de espera progressivamente maiores. Para uma operação de escrita, faça primeiro uma leitura de verificação: busque o registro por uma chave que você controla (storeId, um código de loja, a lista de respostas da interação) e só repita a chamada se o registro realmente estiver ausente.

Códigos comuns

Os códigos de validação no intervalo SY10xxx correspondem a um campo de entrada específico; message indica o campo ou a regra que falhou. Os códigos de autenticação e autorização no intervalo SY90xxx se aplicam à requisição e chegam no nível superior com o status correspondente.

Códigos de contas conectadas

Os códigos no intervalo SY810xx vêm dos endpoints de contas conectadas que importam ou vinculam uma listagem de uma plataforma de publicação. Eles chegam aninhados no corpo da resposta em um HTTP 200 (formato de resposta 2 acima), portanto leia data.<operation>.errors mesmo quando o status indicar sucesso.

Códigos do Social

Os códigos no intervalo SY950xx vêm dos endpoints de Social: marcas, conexões e publicações em redes sociais. Assim como os códigos de contas conectadas, eles chegam aninhados no corpo da resposta em um HTTP 200, portanto, leia data.<operation>.error (e data.<operation>.errors nas rotas em lote) mesmo quando o status indicar sucesso.

SY95042 e SY95044 são falhas de acesso a recursos do plano, não erros de entrada: tentar novamente sem alterar o plano resultará na mesma falha. SY95045, SY95046, SY95049 e SY95052 são erros de entrada que podem ser corrigidos na próxima requisição.

Códigos de direitos de uso do Listings

rate_limited

429 Too Many Requests: a conta excedeu o limite de requisições do plano. O corpo é a resposta de erro padrão, que contém uma indicação em retry_after_seconds, um correlation_id para informar nas solicitações de suporte e um doc_url com um link para esta seção:

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

Aguarde o tempo indicado por retry_after_seconds (ou pelo cabeçalho Retry-After, quando presente) e tente novamente com espera exponencial entre as tentativas. Consulte Limites de requisições para ver os limites por plano e uma implementação de referência de espera entre tentativas.

payment_required

402: O último pagamento desta conta não foi concluído, portanto todos os endpoints /api/v4 estão pausados. O corpo inclui pay_url, a página do Stripe referente à fatura não paga, quando disponível, e o cabeçalho de resposta X-Error-Code contém o mesmo code. Você ainda pode abrir a página de Faturamento no painel para pagar.

{  "code": "payment_required",  "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.",  "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc",  "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}

O acesso é restabelecido em até um minuto após o pagamento da última fatura em aberto. Se a fatura continuar sem pagamento 3 dias após a primeira tentativa de pagamento malsucedida, a assinatura do Listings será cancelada e os locais da conta serão arquivados. Se a conta também tiver uma assinatura ativa do Social, ela manterá o acesso ao Social; caso contrário, a conta será encerrada e suas chaves de API deixarão de funcionar.

social_payment_required

402: O último pagamento da assinatura do Social não foi concluído, portanto os endpoints do Social (/api/v4/social/*) estão pausados. Os endpoints do Listings continuam funcionando. O corpo tem os mesmos campos de payment_required, com "code": "social_payment_required". Se a fatura continuar sem pagamento 3 dias após a primeira tentativa de pagamento malsucedida, a assinatura do Social será cancelada e as marcas da conta serão arquivadas. Uma conta sem assinatura do Listings será encerrada, e suas chaves de API deixarão de funcionar.

Erros do plano de controle do portal do desenvolvedor

Os endpoints de gerenciamento de contas e chaves no portal do desenvolvedor (as rotas de API do próprio painel) retornam uma única resposta de erro estruturada, distinta dos formatos errors[] da API REST apresentados acima. Cada code contém um correlation_id e um doc_url com um link para a seção correspondente nesta página.

{  "error": {    "code": "AUTH_INVALID_KEY",    "message": "Session is invalid or expired.",    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key"  }}

auth_missing_key

401: Nenhuma credencial foi fornecida. Faça login novamente ou envie sua chave como Authorization: API <your-key>.

auth_invalid_key

401: A sessão ou a chave é inválida ou expirou. Autentique-se novamente ou emita uma nova chave pelo painel.

auth_insufficient_scope

403: A credencial é válida, mas não tem permissão para esta ação. Uma chave com escopo de leitura não pode chamar endpoints de escrita; emita uma chave de escrita se precisar.

not_found

404: O recurso solicitado, ou um recurso referenciado por ID, não existe.

conflict

409: A solicitação entra em conflito com o estado atual do recurso (por exemplo, revogar uma chave que já foi revogada).

validation_failed

422: O corpo da solicitação não passou na validação. Os campos field e details da resposta identificam a entrada que causou o problema.

internal_error

500: Um erro inesperado no servidor. Repita uma leitura com espera exponencial entre as tentativas; para uma escrita, leia o registro novamente primeiro (consulte Repetir uma escrita não é isento de custo). Informe o correlation_id se entrar em contato com o suporte.

dependency_unavailable

503: Um serviço do qual a API depende está temporariamente indisponível. Tente novamente com espera entre as tentativas.

Para 429, consulte rate_limited acima.

Tratamento de erros no código

Verifique primeiro o status HTTP; depois, para operações de escrita, procure um array errors aninhado no corpo da resposta:

from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try:    location = client.locations.create(input=payload)except APIError as e:    # Raised for a non-2xx status (AuthenticationError, ValidationError, and    # so on) and for an error payload returned inside a 200 body.    raise RuntimeError(f"Listings API error: {e}") from e

Ao usar a API HTTP diretamente, as mesmas duas verificações são explícitas: primeiro o código de status e depois o payload da resposta:

resp = requests.post(    "https://listingsapi.com/api/v4/locations",    headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"},    json=payload,    timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"):    messages = [e["message"] for e in op["errors"]]    raise RuntimeError(f"Listings API error: {messages}")

O Python SDK faz ambas as verificações para você: ele mapeia cada status HTTP para uma exceção tipada e também lança uma exceção quando há payloads de erro retornados em um corpo 200.