Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt

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

A API Simplo retorna erros no padrão RFC 7807 (Problem Details for HTTP APIs) com Content-Type: application/problem+json. 
{
  "type": "https://problems-registry.smartbear.com/validation-error",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "The request payload contains validation errors",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "detail": "Campo obrigatório não informado", "pointer": "/customer/name" }
  ]
}
CampoO que é
typeURI que identifica o tipo de problema
statusCódigo HTTP (espelha o status da resposta)
titleTítulo legível do problema
detailDescrição específica para esta ocorrência
codeCódigo de erro estável da Simplo (use para lógica programática)
errorsLista de erros de campo (presente em validação) — cada item tem detail e pointer (JSON Pointer apontando para o campo)

​
Códigos de status

CódigoSignificadoAção recomendada
200 OKSucesso na leitura ou atualização—
201 CreatedRecurso criadoGuarde o id da resposta
204 No ContentSucesso sem corpo (ex.: delete)—
400 Bad RequestRequisição malformada (JSON inválido, header errado)Corrija o cliente HTTP
401 UnauthorizedChave de API ausente, inválida ou revogadaVerifique sua autenticação
403 ForbiddenChave válida, mas sem permissão para o recursoConfira se a chave é da conta certa
404 Not FoundRecurso não existe ou pertence a outra contaConfira o id
422 Unprocessable EntityDados não passaram na validação ou regra de negócioVeja errors ou detail para corrigir
429 Too Many RequestsRate limit estouradoAguarde e tente novamente — veja abaixo
500 Internal Server ErrorAlgo deu errado do nosso ladoTente novamente; se persistir, fale com o suporte
503 Service UnavailableManutenção ou indisponibilidade temporáriaTente novamente com backoff

​
Validação (422)

Quando você envia dados inválidos, a resposta detalha cada campo problemático em errors[]: 
{
  "type": "https://problems-registry.smartbear.com/validation-error",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "The request payload contains validation errors",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "detail": "Campo obrigatório não informado", "pointer": "/customer/name" },
    { "detail": "deve ter 11 dígitos (CPF) ou 14 (CNPJ)", "pointer": "/customer/identifier" }
  ]
}
Use pointer (JSON Pointer) para mostrar a mensagem ao lado do campo correto no seu formulário.

​
Regra de negócio (422)

Nem todo 422 é validação de campo. Algumas regras são de negócio — nesse caso, code identifica a regra e detail traz a explicação: 
{
  "type": "https://problems-registry.smartbear.com/business-rule-violation",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "Modo de checkout inválido. Modos válidos: 'subscription', 'payment'",
  "code": "INVALID_MODE"
}

​
Autenticação (401)

{
  "type": "https://problems-registry.smartbear.com/unauthorized",
  "status": 401,
  "title": "Unauthorized",
  "detail": "Chave de API inválida ou ausente.",
  "code": "UNAUTHORIZED"
}
Causas comuns:
  • Header faltando o prefixo ApiKey (com espaço).
  • Chave revogada no painel.
  • Usando chave de sandbox em produção (ou vice-versa).

​
Rate limit (429)

{
  "type": "https://problems-registry.smartbear.com/too-many-requests",
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Limite de requisições excedido. Tente novamente em alguns instantes.",
  "code": "RATE_LIMITED"
}
A resposta inclui o header Retry-After em segundos. Implemente backoff exponencial: 
# Ruby
def with_retry(max_attempts: 5)
  attempts = 0
  begin
    attempts += 1
    yield
  rescue Simplo::RateLimit => e
    raise if attempts >= max_attempts
    sleep(e.retry_after || 2 ** attempts)
    retry
  end
end
Não faça retry imediato em loop apertado. Isso piora o problema e pode estender o bloqueio.

​
Erros do servidor (5xx)

500 e 503 são raros, mas acontecem. Trate-os como transitórios:
  1. Espere alguns segundos.
  2. Tente de novo com backoff exponencial.
  3. Se persistir por mais de 5 minutos, verifique status.besimplo.com.
Como a API ainda não suporta Idempotency-Key em requisições, retries em operações financeiras (POST /checkout/sessions, POST /refunds, etc.) podem gerar duplicidade. Em caso de timeout numa operação que mexe em dinheiro, consulte o recurso antes de retentar para confirmar se ele já foi criado.