Primeiros passos
Erros
A API usa códigos de status HTTP convencionais para indicar o sucesso ou a falha de uma requisição.
| Código | Descrição |
|---|---|
| 200 | Requisição bem-sucedida |
| 201 | Recurso criado com sucesso |
| 202 | Aceita, mas aguardando a aprovação de uma pessoa da empresa (limites de agentes). |
| 400 | Requisição inválida: revise os parâmetros |
| 401 | Não autorizado: chave de API inválida ou ausente |
| 403 | Proibido: você não tem permissão para este recurso |
| 404 | Recurso não encontrado |
| 422 | Erro de validação |
| 429 | Limite de requisições excedido |
| 500 | Erro interno do servidor |
Formato de erro
{
"error": {
"type": "validation_error",
"code": "invalid_parameter",
"message": "El campo email es requerido",
"param": "email",
"doc_url": "https://docs.recaudo.app/errors/invalid_parameter"
}
}Novas tentativas seguras (Idempotency-Key)
Envie o cabeçalho Idempotency-Key com um valor único em cada POST, PUT ou DELETE. Se repetir a requisição com a mesma chave e o mesmo corpo, você recebe a resposta original com Idempotent-Replayed: true e a operação não se repete. A mesma chave com outro corpo retorna 422 (idempotency_key_reused); enquanto a primeira ainda está rodando, 409. As chaves duram 24 horas.
Limites de agentes
Se você chamar com o token de um app conectado (Claude, ChatGPT ou seu próprio agente via OAuth), as operações com dinheiro passam pelos limites que a empresa define em Configurações → Agentes e pagamentos. Acima do limite a resposta é 202 com um objeto agent_payment_action em status pending; consulte GET /v1/agent-payment-actions/{id} até que diga approved (em result vem o que foi criado), rejected ou expired. Se a ação não for permitida, 403 com o tipo agent_limit_error. As API keys não têm limites, a menos que a empresa defina um.