Erros · Astorya para Parceiros

Nesta página

Formato
Códigos
Quando tentar de novo

Formato

Exemplo: 409 Conflict

{
  "statusCode": 409,
  "code": "EMAIL_CONFLICT",
  "message": "Este e-mail já pertence a outro usuário."
}

Nos erros de validação, message é uma lista, com uma frase por problema encontrado:

Exemplo: 400 Bad Request

{
  "statusCode": 400,
  "code": "VALIDATION",
  "message": [
    "externalUserId must be shorter than or equal to 128 characters",
    "redirectPath must start with /"
  ]
}

Códigos

Código	HTTP	Quando acontece	Como tratar
`VALIDATION`	400	Corpo ou parâmetros inválidos: campo obrigatório ausente, formato errado, `month` fora de `AAAA-MM`.	Erro de programação: registre `message` (lista) e corrija. Não repita a mesma chamada.
`INVALID_CLIENT`	401	Cabeçalho `Authorization` ausente ou malformado, `client_id` desconhecido, segredo errado ou credencial revogada.	Confira a credencial do ambiente certo. Alerte o seu time: provavelmente houve rotação. Veja Autenticação.
`USER_REVOKED`	403	Pedido de sessão para um membro revogado (`DELETE`) ou bloqueado (`status: "BLOCKED"`).	Mostre no app que o benefício não está ativo. Para reativar: `PUT` com `status: "ACTIVE"`.
—	404	`GET` ou `DELETE` de um `externalUserId` que não existe no seu tenant.	No `DELETE`, trate como sucesso: não há nada a revogar.
`EMAIL_CONFLICT`	409	O e-mail enviado já pertence a outro membro do seu tenant.	Repita sem `email` e corrija a duplicidade no seu cadastro. Veja E-mail e vínculo.
`RATE_LIMITED`	429	Mais de 120 requisições por minuto com a mesma credencial.	Espere e tente de novo com backoff exponencial; respeite `Retry-After` se vier. Veja Limites.
`INVALID_LAUNCH_TOKEN`	401	Na troca do token feita pelo Astorya Web: link expirado (mais de 60 s), já usado ou inválido. Você não recebe esse erro na sua API: ele aparece para o app como o evento `astorya:session-expired`.	Peça uma nova sessão e recarregue a WebView. Veja Quando o link expira.
—	5xx	Falha temporária do nosso lado.	Tente de novo com backoff (até 3 vezes). Se persistir, escreva para contatodanielmrocha@gmail.com com o horário e o endpoint.

Quando tentar de novo

Pode repetir: 429, 5xx e falhas de rede. PUT e DELETE são idempotentes. Um POST /sessions repetido só gera outro link — o anterior expira sozinho.
Não adianta repetir: 400, 401, 403 e 409. Corrija a causa antes.

Node.js — retentativa com backoff

export async function withRetry(call, attempts = 4) {
  for (let i = 0; ; i++) {
    const res = await call();
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || i === attempts - 1) return res;
    const retryAfter = Number(res.headers.get('retry-after'));
    const waitMs = retryAfter > 0 ? retryAfter * 1000 : 2 ** i * 1000;
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }
}