Error Handling

The VRP Billing API uses standard HTTP status codes and returns detailed error bodies to help you diagnose issues quickly. All error responses are JSON objects containing type, code, message, and optionally details.

Error Response Model

{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The field 'currency' is required.",
    "param": "currency"
  }
}

Field	Description
`error.type`	Broad classification (`invalid_request`, `authentication_error`, `authorization_error`, `rate_limit_error`, `api_error`).
`error.code`	Machine-readable identifier for the specific error.
`error.message`	Human-readable description intended for logs and dashboards.
`error.param`	(Optional) Parameter or header associated with the error.

HTTP Status Codes

Status	When returned
`400 Bad Request`	Invalid parameters, malformed JSON, business rule violations.
`401 Unauthorized`	Missing or invalid bearer token.
`403 Forbidden`	API key lacks permission for the requested resource.
`404 Not Found`	Resource does not exist or belongs to another merchant.
`409 Conflict`	Duplicate resource or state transition not allowed.
`422 Unprocessable Entity`	Validation succeeded but bank-level constraints rejected the request.
`429 Too Many Requests`	Rate limit exceeded (see Rate Limits).
`500 Internal Server Error`	Unexpected issue on VRP Billing's side.
`503 Service Unavailable`	Temporary outage or scheduled maintenance. Retry with backoff.

Common Error Codes

Code	Description	Resolution
`missing_parameter`	Required field was omitted.	Provide the missing field and retry with a new idempotency key.
`invalid_currency`	Unsupported currency code.	Use a supported currency from Mandates.
`amount_over_limit`	Amount exceeds mandate or bank limits.	Lower the amount or adjust mandate parameters.
`mandate_not_active`	Mandate is not in `active` status.	Wait for `mandate.activated` webhook or create a new mandate.
`duplicate_idempotency_key`	Reused idempotency key with different parameters.	Generate a unique key per logical operation.
`idempotency_key_locked`	A request with the supplied idempotency key is still being processed.	Retry with the same key after the initial request completes.
`webhook_endpoint_blocked`	Endpoint repeatedly failed deliveries.	Resolve issues and request reactivation from support.

Error Logging Best Practices

Avoid displaying message to end users; provide a generic message instead.
Implement alerting for recurring api_error or service_unavailable responses.

Support Escalation

If you encounter persistent api_error responses, contact support with:

Timestamp and timezone
Endpoint called and request payload (sanitised)
Response body

This information speeds up triage and resolution.