Erros e respostas HTTP

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`	JSON inválido, ou nenhum campo reconhecido no corpo	Veja `detail` — ele lista os campos aceitos
`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

Corpo não reconhecido (400)

Se o corpo não traz nenhum campo que o endpoint aceita, a resposta nomeia o parâmetro rejeitado e lista os campos esperados — você não precisa descobrir o formato por tentativa e erro:

{
  "type": "https://problems-registry.smartbear.com/missing-body-property",
  "status": 400,
  "title": "Bad Request",
  "detail": "The 'invoice' parameter is required and must contain at least one recognized field. Expected fields: customer_id, external_code, line_items, discounts.",
  "code": "PARAMETER_MISSING",
  "errors": [
    { "detail": "No recognized field was found in 'invoice'.", "pointer": "/invoice" }
  ]
}

A causa mais comum é o nome errado de um campo — por exemplo, enviar customer onde o endpoint espera customer_id. Compare detail com o corpo que você enviou. Quando o corpo nem sequer é JSON válido, o code é MALFORMED_JSON:

{
  "type": "https://problems-registry.smartbear.com/bad-request",
  "status": 400,
  "title": "Bad Request",
  "detail": "The request body is not valid JSON",
  "code": "MALFORMED_JSON"
}

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:

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 /invoices/:id/checkout, 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.

Comece por aqui

Conceitos

Erros e respostas HTTP

Códigos de status

Corpo não reconhecido (400)

Validação (422)

Regra de negócio (422)

Autenticação (401)

Rate limit (429)

Erros do servidor (5xx)

​Códigos de status

​Corpo não reconhecido (400)

​Validação (422)

​Regra de negócio (422)

​Autenticação (401)

​Rate limit (429)

​Erros do servidor (5xx)

Códigos de status

Corpo não reconhecido (400)

Validação (422)

Regra de negócio (422)

Autenticação (401)

Rate limit (429)

Erros do servidor (5xx)