Códigos de erro

A API da PolyTest usa os códigos de status HTTP padrão. Todas as respostas de erro retornam um corpo JSON com um campo error que descreve o problema.

Depurando um erro da API da Polymarket? Esta página trata da API da PolyTest. Para os erros da própria Polymarket — 425, 429, modo somente cancelamento, divergências de signer e os que faltam na documentação deles — veja nossa referência de erros da Polymarket.

Formato da resposta de erro: todos os erros retornam um objeto JSON com uma única chave "error" contendo uma mensagem legível. O código de status HTTP indica a categoria do erro.

400Bad Request

A requisição está malformada ou faltam parâmetros obrigatórios.

{ "error": "timestamp query parameter is required" }

Causas comuns

Falta um parâmetro de consulta obrigatório
Formato de parâmetro inválido (ex.: timestamp fora do padrão ISO 8601)
Valor de parâmetro fora do intervalo permitido

401Unauthorized

Falha na autenticação — a requisição não tem credenciais válidas.

{ "error": "Invalid API key" }

Causas comuns

Falta o header X-API-Key ou o header Authorization
A chave de API não existe ou é inválida
A chave de API foi revogada
A chave de API expirou
O token JWT é inválido ou expirou

403Forbidden

As credenciais são válidas, mas não têm permissão para esta ação.

{ "error": "Admin access required" }

Causas comuns

Tentativa de acessar endpoints exclusivos de administrador (sync, seed) sem privilégios de administrador
O escopo da chave de API não inclui a permissão necessária

404Not Found

O recurso solicitado não existe.

{ "error": "Market not found" }

Causas comuns

O ID do mercado não existe
O slug do mercado não corresponde a nenhum registro
Nenhum snapshot encontrado em até ±2 segundos do timestamp informado

429Too Many Requests

Limite de requisições excedido. Aguarde e tente de novo depois do tempo indicado.

{ "error": "Rate limit exceeded" }

Causas comuns

Limite de requisições por minuto do seu plano excedido
Limite de pico excedido (requisições demais em uma janela curta)

500Internal Server Error

Ocorreu um erro inesperado no servidor. Eles são raros — se persistir, fale com o suporte.

{ "error": "Internal server error" }

Causas comuns

Problema de conexão com o banco de dados
Falha em um serviço upstream
Exceção inesperada no servidor

Como lidar com erros

Erros do cliente (4xx)

Não tente de novo automaticamente. Corrija os parâmetros da requisição ou a autenticação, ou verifique se o recurso existe, antes de tentar de novo.

Erros do servidor (5xx)

É seguro tentar de novo com backoff exponencial. Comece com um atraso de 1 segundo e dobre a cada tentativa, até 3 novas tentativas.

import time
import requests

def api_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue

        if response.status_code >= 500:
            time.sleep(2 ** attempt)
            continue

        return response

    raise Exception("Max retries exceeded")