Error Handling

The BRZ API uses standard HTTP status codes and returns structured JSON error responses.

HTTP Status Codes

Error Response Format

All error responses follow this structure:

1
{
2
  "success": false,
3
  "error": "Human-readable error message",
4
  "code": "MACHINE_READABLE_ERROR_CODE"
5
}

Common Error Codes

Authentication Errors

Validation Errors

Transaction Errors

Limit Errors

Idempotency

Use the X-Idempotency-Key header (UUID format) to prevent duplicate operations. If you send the same idempotency key twice, the API returns the original response instead of creating a duplicate.

$
curl -X POST https://api.brzip.com.br/api/v1/pix/cash-out \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json" \
>
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
>
  -d '{ "amount": "100.00", "pix_key": "12345678901", "pix_key_type": "CPF" }'