Erros

A API do Scavio usa códigos de status HTTP padrão e retorna respostas de erro estruturadas para ajudar você a depurar problemas rapidamente.

Formato da Resposta de Erro

JSON

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable error description"
  }
}

Códigos de Status

Status	Código	Descrição
400	`bad_request`	Corpo da solicitação inválido ou parâmetros obrigatórios ausentes
401	`unauthorized`	Chave de API ausente ou inválida
403	`forbidden`	A chave de API não tem permissão para esta ação
402	`insufficient_credits`	Nenhum crédito restante. Recarregue ou faça upgrade do seu plano.
429	`rate_limit_exceeded`	Muitas solicitações. Aguarde e tente novamente.
500	`internal_error`	Erro do servidor. Tente novamente após um breve intervalo.

Erros Comuns

Parâmetro de consulta ausente

400 Solicitação Inválida

{
  "error": {
    "code": "bad_request",
    "message": "The 'query' field is required"
  }
}

search_type inválido

400 Solicitação Inválida

{
  "error": {
    "code": "bad_request",
    "message": "Invalid search_type. Must be one of: classic, news, maps, images, lens"
  }
}

Chave de API inválida

401 Não Autorizado

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Créditos insuficientes

402 Pagamento Necessário

{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits remaining. Please upgrade your plan or purchase additional credits."
  }
}

Limite de taxa excedido

429 Muitas Solicitações

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}

Melhores Práticas

Sempre verifique o código de status HTTP antes de analisar o corpo da resposta
Use o campo error.code para tratamento programático de erros
Use o campo error.message para registro e depuração
Implemente lógica de repetição com backoff exponencial para erros 429 e 500
Não repita erros 400 ou 401 — corrija a solicitação primeiro

Códigos de Status

Status

Código

Descrição

400

bad_request

Corpo da solicitação inválido ou parâmetros obrigatórios ausentes

401

unauthorized

Chave de API ausente ou inválida

403

forbidden

A chave de API não tem permissão para esta ação

402

insufficient_credits

Nenhum crédito restante. Recarregue ou faça upgrade do seu plano.

429

rate_limit_exceeded

Muitas solicitações. Aguarde e tente novamente.

500

internal_error

Erro do servidor. Tente novamente após um breve intervalo.

Erros Comuns

Parâmetro de consulta ausente

400 Solicitação Inválida

{
  "error": {
    "code": "bad_request",
    "message": "The 'query' field is required"
  }
}

search_type inválido

400 Solicitação Inválida

{
  "error": {
    "code": "bad_request",
    "message": "Invalid search_type. Must be one of: classic, news, maps, images, lens"
  }
}

Chave de API inválida

401 Não Autorizado

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Créditos insuficientes

402 Pagamento Necessário

{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits remaining. Please upgrade your plan or purchase additional credits."
  }
}

Limite de taxa excedido

429 Muitas Solicitações

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}

Melhores Práticas

Sempre verifique o código de status HTTP antes de analisar o corpo da resposta

Use o campo error.code para tratamento programático de erros

Use o campo error.message para registro e depuração

Implemente lógica de repetição com backoff exponencial para erros 429 e 500

Não repita erros 400 ou 401 — corrija a solicitação primeiro