REST API guide

REST API Base Endpoint

https://avraapi.com/api/v1

The REST API is the advanced integration path for backends that need direct HTTP control or do not yet have a matching SDK capability. The /v1 segment is part of every public service URL.

URL format and API version

Every service path is appended to the same versioned base endpoint:

https://avraapi.com/api/v1/{service-path}

Each reviewed operation page shows its complete API URL above the request details so there is no ambiguity about where a request is sent.

Common request headers

Header	Required	Purpose
`X-API-KEY`	Yes	Your project Client ID.
`X-API-SECRET`	Yes	Your project Client Secret. Send only from a trusted backend.
`X-ENV`	No	Selects the project environment. Omit it for Development.
`Accept`	Recommended	Use `application/json` for operations that return JSON.
`X-Privacy-Mode`	Optional	Per-request privacy control. Send `1` when you do not want AvraAPI to retain normal request and provider-response observability payload data; billing and usage tracking continue.

The runtime accepts dev or development for Development, and prod or production for Production. Credentials and environment are resolved together: changing X-ENV does not turn a Development credential into a Production credential.

X-API-KEY: your_project_client_id
X-API-SECRET: your_project_client_secret
X-ENV: development
Accept: application/json

X-Privacy-Mode

X-Privacy-Mode is an optional privacy control for an individual API request. Send a truthy value such as 1 when the request contains data that should not be retained in normal observability payload logs.

X-Privacy-Mode: 1

Privacy Mode does not change authentication, routing, provider execution, billing, rate limiting, or usage tracking. The request runs normally, but AvraAPI does not retain the request body, non-routing request headers, provider response body, or provider response headers for that request. Only the minimum billing and usage metadata needed to operate the service is retained, including the request time, service, project and environment identifiers, credit cost, and response status. Use it deliberately for sensitive request data. It is not anonymous processing and does not remove the request’s billing or usage record. See X-Privacy-Mode — The Privacy Guarantee for the complete legal terms.

Common response behaviour

JSON provider operations use AvraAPI response envelopes. A successful operation includes success, request_id, and its operation-specific data. Error responses include success: false, request_id, a stable error.code, and a readable error.message. Some infrastructure errors also include meta; do not depend on meta being present for every operation-level validation error. The X-APIX-Request-ID response header mirrors the request identifier. Keep it when troubleshooting an API issue. Rate-limited operations return 429 and may include Retry-After; wait for that period instead of retrying in a tight loop. Media operations are documented separately because they can return image or PDF content instead of JSON. Their exact request and response media types are defined on the relevant Utilities pages.

Live Testing Guide: Before using Try it, create a Development project, then enter its Client ID and Client Secret. Configure the relevant provider for that project before sending the request.

Error-code reference

Handle every non-2xx response by HTTP status and error.code. Keep the request_id with your application logs and support request; it is also returned in the X-APIX-Request-ID header.

Typical JSON error envelope

{
  "success": false,
  "request_id": "01j...",
  "error": {
    "code": "validation_error",
    "message": "The request data is invalid."
  },
  "meta": {
    "provider_override": null
  }
}

meta is optional. In particular, directly validated operations can return a more specific error.details object instead.

Common platform errors

These codes are produced by the shared API middleware, the common exception renderer, or the Gateway request runtime. They can occur across more than one provider service.

HTTP	`error.code`	Meaning	Recommended handling
`401`	`unauthorized`	Project credentials are missing, invalid, inactive, or do not match `X-ENV`.	Check the Client ID, Client Secret, and environment. Do not retry unchanged credentials.
`402`	`insufficient_funds`	The selected paid service cannot reserve the required AvraAPI credits.	Add credits or use an eligible plan, then retry the request once.
`403`	`forbidden`	Credentials are valid but the action is not permitted.	Check the project, environment, service configuration, and operation rules.
`404`	`resource_not_found`	The request URL or requested public resource does not exist.	Check the HTTP method, API version, and path parameters.
`404`	`wallet_not_found`	A required wallet record is unavailable for a billable request.	Do not retry in a loop. Keep the request ID and contact support.
`405`	`method_not_allowed`	The endpoint exists but does not support the HTTP method used.	Use the documented method for that endpoint.
`409`	`conflict`	The request conflicts with the current state of a resource.	Read the endpoint-specific response and reconcile your application state before retrying.
`413`	`payload_too_large`	The request body exceeds the allowed size.	Reduce the body size or use the documented media/input alternative.
`415`	`unsupported_media_type`	The request content type is not accepted.	Set the endpoint’s documented `Content-Type` and body format.
`422`	`validation_error`	A request did not satisfy framework-level input validation.	Correct the invalid field values and submit a new request.
`422`	`provider_selection_failed`	No eligible provider integration can be selected for the project environment.	Configure or enable the service provider in the selected environment, then retry.
`429`	`rate_limit_exceeded`	The configured request limit has been reached.	Wait for `Retry-After` before retrying with backoff.
`500`	`internal_error`	AvraAPI could not complete the request.	Retry only when your operation is safe to retry; retain the request ID if it continues.
`503`	`project_paused`	The project is paused and cannot make API requests.	Reactivate the project before retrying.

Operation-specific errors

Some operations expose additional stable errors because they have their own input or service rules. Their endpoint page is the source of truth for those codes and response details.

Area	Examples	Where to check
Currency	`invalid_currency_code`, `validation_failed`	The relevant Currency endpoint page.
Location, Security, SMS, and Utilities	Request-field, provider, billing, or media-specific validation errors	The individual provider endpoint page once that API contract is published.

Some exception names are used internally for observability or billing decisions but are not independently published as stable HTTP error.code values. This reference intentionally documents only codes that the public API contract can return to an integration.

Security boundary

Do not call the REST API from public frontend code. Your backend should read Client ID and Client Secret values from environment configuration or a managed secret store, then make the AvraAPI request on behalf of your application. See Authentication & credentials for credential lifecycle guidance and API key safety for incident response.

Introduction

Currencies

SMS

Security

Location

Utilities

URL format and API version

Common request headers

X-Privacy-Mode

Common response behaviour

Error-code reference

Common platform errors

Operation-specific errors

Security boundary

​URL format and API version

​Common request headers

​X-Privacy-Mode

​Common response behaviour

​Error-code reference

​Common platform errors

​Operation-specific errors

​Security boundary

URL format and API version

Common request headers

X-Privacy-Mode

Common response behaviour

Error-code reference

Common platform errors

Operation-specific errors

Security boundary