Referência de códigos de erro

Esta página documenta todos os códigos de erro retornados pela API omegaUp, seus códigos de status HTTP e causas comuns.

Formato de resposta de erro

Todos os erros da API seguem este formato:

{
  "status": "error",
  "error": "Human-readable error message",
  "errorname": "errorKeyName",
  "errorcode": 400,
  "header": "HTTP/1.1 400 BAD REQUEST",
  "parameter": "field_name"
}

Códigos de status HTTP

400 Solicitação incorreta

Entrada inválida ou erros de parâmetro.

Exemplo:

{
  "status": "error",
  "error": "problem_alias: Parameter is invalid",
  "errorname": "parameterInvalid",
  "errorcode": 400,
  "parameter": "problem_alias"
}

401 Não autorizado

Autenticação necessária ou inválida.

Exemplo:

{
  "status": "error",
  "error": "Login required",
  "errorname": "loginRequired",
  "errorcode": 401
}

403 Proibido

Autenticado, mas não autorizado.

Exemplo:

{
  "status": "error",
  "error": "User is not allowed to perform this action",
  "errorname": "userNotAllowed",
  "errorcode": 403
}

404 não encontrado

O recurso solicitado não existe.

Exemplo:

{
  "status": "error",
  "error": "Problem not found",
  "errorname": "problemNotFound",
  "errorcode": 404
}

409 Conflito

Conflito de estado de recurso.

Exemplo:

{
  "status": "error",
  "error": "User is already a member of this group",
  "errorname": "identityInGroup",
  "errorcode": 409
}

412 Falha na pré-condição

Restrição de lógica de negócios não atendida.

429 Muitas solicitações

Limite de taxa excedido.

Cabeçalhos incluídos:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704070800
Retry-After: 3600

500 Erro interno do servidor

Erros do lado do servidor.

503 Serviço indisponível

Serviço temporariamente indisponível.

Cenários de erros comuns

Erros de autenticação

// Wrong password
{
  "errorname": "invalidCredentialsException",
  "errorcode": 401
}

// Not logged in
{
  "errorname": "loginRequired", 
  "errorcode": 401
}

// Email not verified
{
  "errorname": "emailNotVerified",
  "errorcode": 401
}

Erros de validação

// Missing required field
{
  "errorname": "parameterEmpty",
  "parameter": "name",
  "errorcode": 400
}

// Invalid format
{
  "errorname": "parameterInvalid",
  "parameter": "email",
  "errorcode": 400
}

// Alias taken
{
  "errorname": "aliasInUse",
  "errorcode": 400
}

Erros de permissão

// Not contest admin
{
  "errorname": "userNotAllowed",
  "errorcode": 403
}

// Contest not open yet
{
  "errorname": "contestNotStarted",
  "errorcode": 403
}

Práticas recomendadas para tratamento de erros

Tratamento do lado do cliente

async function makeAPICall(endpoint, data) {
  const response = await fetch(endpoint, {
    method: 'POST',
    body: JSON.stringify(data)
  });

  const result = await response.json();

  if (result.status === 'error') {
    switch (result.errorcode) {
      case 401:
        // Redirect to login
        window.location.href = '/login/';
        break;
      case 403:
        // Show permission error
        alert(result.error);
        break;
      case 404:
        // Resource not found
        showNotFoundMessage(result.error);
        break;
      case 429:
        // Rate limited - retry after delay
        const retryAfter = response.headers.get('Retry-After');
        setTimeout(() => makeAPICall(endpoint, data), retryAfter * 1000);
        break;
      default:
        // Generic error handling
        console.error(result.error);
    }
    return null;
  }

  return result;
}

Verificando erros específicos

if (result.errorname === 'aliasInUse') {
  // Suggest alternative alias
  suggestAlternative(data.alias);
}

Localização

As mensagens de erro são localizadas com base na preferência de idioma do usuário. O campo errorname permanece constante em todas as linguagens para manipulação programática.

Documentação Relacionada

• Referência da API - Visão geral da API
• Autenticação - Fluxo de autenticação e erros

Referência completa

Para obter a lista completa de classes de exceção, consulte o diretório de exceções no código-fonte.