Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stric.io/llms.txt

Use this file to discover all available pages before exploring further.

A Stric usa códigos de status HTTP convencionais e retorna um corpo JSON com detalhes estruturados.

​
Estrutura de erro

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Saldo insuficiente para concluir a operação.",
    "details": {
      "available": "5000",
      "requested": "10000"
    }
  }
}
CampoDescrição
error.codeCódigo estável (use em lógica de tratamento de erros)
error.messageMensagem human-readable
error.detailsContexto adicional (campos com problema, valores) — opcional

​
Correlacionação e suporte

Além do JSON de erro, guarde na sua aplicação o status HTTP e qualquer valor único disponível nos headers da resposta (ids de correlacionação costumam vir aí quando o gateway os expõe). Ao acionar o suporte, passe error.code, o status HTTP e esse identificador, se você o tiver nos logs — facilita encontrar a requisição exata nos nossos sistemas.

​
Códigos por status

​
400 — VALIDATION_ERROR

Body, query ou parâmetros inválidos. details lista os campos com problema. 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campos inválidos no request.",
    "details": {
      "amountCents": "deve ser uma string ou número em centavos"
    }
  }
}

​
401 — UNAUTHORIZED

API key ausente, malformada, expirada ou revogada.

​
403 — FORBIDDEN

A key não tem permissão para a operação ou para o recurso.

​
404 — NOT_FOUND

Recurso inexistente. error.code indica qual (CHARGE_NOT_FOUND, PAYOUT_NOT_FOUND — transferência Pix em /v1/payouts/{id}, etc.).

​
409 — IDEMPOTENCY_CONFLICT

Mesma Idempotency-Key usada com body diferente. Gere uma nova key. Ver Idempotência.

​
422 — Erros de domínio

Operação rejeitada por regra de negócio. Códigos comuns:
CódigoQuando acontece
INSUFFICIENT_BALANCESaldo da conta menor que o valor da operação
INVALID_STATEEstado do recurso não permite a ação (ex.: cobrança já paga)
LIMIT_EXCEEDEDLimite diário/mensal de pagamento excedido
DICT_KEY_NOT_FOUNDChave Pix não existe no diretório (lookup)
BR_CODE_INVALIDBR Code expirado ou inválido

​
429 — RATE_LIMIT_EXCEEDED

Você excedeu o limite de requisições. A resposta inclui o header Retry-After em segundos. 
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Implemente exponential backoff respeitando esse cabeçalho. Ver Rate limits.

​
500 — INTERNAL_ERROR

Erro inesperado do nosso lado. Geralmente seguro para retry com exponential backoff.

​
Padrão de tratamento

async function callStric(path, options = {}) {
  const r = await fetch(`${process.env.STRIC_BASE_URL}${path}`, options);

  if (r.ok) return r.json();

  const body = await r.json().catch(() => ({}));
  const code = body?.error?.code ?? "UNKNOWN";

  switch (code) {
    case "INSUFFICIENT_BALANCE":
      throw new BusinessError("Saldo insuficiente", body.error.details);
    case "RATE_LIMIT_EXCEEDED":
      const retryAfter = parseInt(r.headers.get("Retry-After") ?? "5", 10);
      await sleep(retryAfter * 1000);
      return callStric(path, options); // retry
    case "UNAUTHORIZED":
    case "FORBIDDEN":
      throw new AuthError(body.error.message);
    default:
      throw new ApiError(r.status, code, body.error?.message);
  }
}
Sempre logue error.code (não só a mensagem). Códigos são estáveis; mensagens podem mudar e estão em português.