Getting started
Errors
The API uses conventional HTTP status codes to indicate the success or failure of a request.
| Code | Description |
|---|---|
| 200 | Successful request |
| 201 | Resource created successfully |
| 202 | Accepted, but waiting for a person at the business to approve it (agent limits). |
| 400 | Invalid request: check the parameters |
| 401 | Unauthorized: invalid or missing API key |
| 403 | Forbidden: you do not have permission for this resource |
| 404 | Resource not found |
| 422 | Validation error |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Error format
{
"error": {
"type": "validation_error",
"code": "invalid_parameter",
"message": "El campo email es requerido",
"param": "email",
"doc_url": "https://docs.recaudo.app/errors/invalid_parameter"
}
}Safe retries (Idempotency-Key)
Send the Idempotency-Key header with a unique value on every POST, PUT or DELETE. If you repeat the request with the same key and body, you get the original response with Idempotent-Replayed: true and the operation is not repeated. The same key with a different body returns 422 (idempotency_key_reused); while the first one is still running, 409. Keys last 24 hours.
Agent limits
If you call with a connected app token (Claude, ChatGPT or your own agent via OAuth), money operations go through the limits the business sets in Settings → Agents and payments. Above the limit the response is 202 with an agent_payment_action object in pending status; poll GET /v1/agent-payment-actions/{id} until it says approved (result holds what was created), rejected or expired. If the action is not allowed, 403 with type agent_limit_error. API keys have no limits unless the business sets one.