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" }
]
}
| Campo | O que é |
|---|
type | URI que identifica o tipo de problema |
status | Código HTTP (espelha o status da resposta) |
title | Título legível do problema |
detail | Descrição específica para esta ocorrência |
code | Código de erro estável da Simplo (use para lógica programática) |
errors | Lista 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ódigo | Significado | Ação recomendada |
|---|
200 OK | Sucesso na leitura ou atualização | — |
201 Created | Recurso criado | Guarde o id da resposta |
204 No Content | Sucesso sem corpo (ex.: delete) | — |
400 Bad Request | Requisição malformada (JSON inválido, header errado) | Corrija o cliente HTTP |
401 Unauthorized | Chave de API ausente, inválida ou revogada | Verifique sua autenticação |
403 Forbidden | Chave válida, mas sem permissão para o recurso | Confira se a chave é da conta certa |
404 Not Found | Recurso não existe ou pertence a outra conta | Confira o id |
422 Unprocessable Entity | Dados não passaram na validação ou regra de negócio | Veja errors ou detail para corrigir |
429 Too Many Requests | Rate limit estourado | Aguarde e tente novamente — veja abaixo |
500 Internal Server Error | Algo deu errado do nosso lado | Tente novamente; se persistir, fale com o suporte |
503 Service Unavailable | Manutenção ou indisponibilidade temporária | Tente 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" }
]
}
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"
}
- 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"
}
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:
- Espere alguns segundos.
- Tente de novo com backoff exponencial.
- 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.
