Tratamento de Erros

Entenda as respostas de erro da API e como tratá-las

Quando uma requisição falha, a API retorna um objeto JSON com uma estrutura consistente.

Formato de Erro

{
  "type": "ErrorType",
  "detail": "Descrição legível do que deu errado"
}

Campo	Descrição
`type`	Identificador de erro legível por máquina
`detail`	Explicação legível por humanos

Códigos de Erro

Status	Tipo	Quando Ocorre
400	`ValueError`	Parâmetros de consulta inválidos (ex. `limit` > 100)
401	`UnauthorizedError`	API key ausente, inválida, expirada ou revogada
402	`InsufficientFundsError`	A conta não pode pagar a mensagem — apenas em `POST /v1/template-messages`. Veja Carrinho Abandonado
403	`ForbiddenError`	A key não tem o escopo que o endpoint exige — ver Autenticação
404	`NotFoundError`	O recurso solicitado não existe
422	`ValidationError`	O body da requisição tem campos inválidos ou ausentes
429	`RateLimitExceededError`	Limite de requisições excedido — ver Rate Limiting
500	`InternalServerError`	Erro inesperado do servidor
502	`UpstreamError`	Um serviço interno falhou. Tente novamente mais tarde

Exemplos

400 Bad Request

{
  "type": "ValueError",
  "detail": "limit must not exceed 100"
}

Solução: Verifique seus parâmetros de consulta. limit deve estar entre 1 e 100, e page deve ser 1 ou maior.

401 Unauthorized

{
  "type": "UnauthorizedError",
  "detail": "Invalid or missing API key"
}

Solução: Verifique que o header X-API-Key está presente e contém uma key válida e ativa.

403 Forbidden

{
  "type": "ForbiddenError",
  "detail": "Missing required scope: orders:read"
}

Solução: Sua key é válida mas não tem o escopo que esse endpoint exige. Hoje as keys são criadas com acesso completo, então esse erro não deveria aparecer; se você vê-lo, entre em contato com o suporte. Ver Autenticação.

404 Not Found

{
  "type": "NotFoundError",
  "detail": "Order 99999 not found"
}

Solução: Verifique que o ID do recurso existe e pertence à sua conta de merchant.

429 Too Many Requests

{
  "type": "RateLimitExceededError",
  "detail": "Rate limit exceeded"
}

Solução: Espere o tempo indicado no header Retry-After antes de tentar novamente. Ver Rate Limiting para boas práticas.

422 Validation Error

Erros 422 usam um formato diferente: detail é um array de objetos (formato Pydantic/FastAPI), não uma string.

{
  "detail": [
    {
      "loc": ["body", "option_values"],
      "msg": "List should have at least 1 item",
      "type": "too_short"
    }
  ]
}

Campo	Descrição
`loc`	Localização do campo que falhou (ex. `["body", "name"]`)
`msg`	Descrição do erro de validação
`type`	Tipo de erro do Pydantic (não é o mesmo `type` do formato padrão)

Solução: Verifique o body da sua requisição. Consulte o API Reference para ver os campos obrigatórios.

502 Bad Gateway

{
  "type": "UpstreamError",
  "detail": "An internal service error occurred. Please try again later."
}

Solução: Um serviço interno falhou. Sua requisição é válida — tente novamente após alguns segundos. Se persistir, entre em contato com o suporte.

500 Internal Server Error

{
  "type": "InternalServerError",
  "detail": "Internal server error"
}

Solução: Este é um problema do servidor. Tente novamente após um breve delay. Se o problema persistir, entre em contato com o suporte.

Tratando Erros no Código

import httpx

response = httpx.get(
    "https://api.ya.onl/v1/orders",
    headers={"X-API-Key": "yv_live_v1_sua_api_key"},
)

if response.status_code == 200:
    orders = response.json()["data"]
elif response.status_code == 429:
    retry_after = int(response.headers["Retry-After"])
    print(f"Rate limited. Retry in {retry_after}s")
else:
    error = response.json()
    print(f"Error [{response.status_code}]: {error['type']} - {error['detail']}")