Send Your First Request
This guide walks you through your first authenticated request to the Partnership API. You’ll retrieve your default partner link—the link you can share to refer clients to Exness. This simple example helps you confirm that your API credentials are set up correctly.
Before you begin
API credentials
Create an API key and store your credentials securely as described in API Key & Host Setup. Under Partnership, select Read-only (
partnership.all:read) for this example. Full access (partnership.all) also supports this request.Identity verification
Complete the identity verification required for your partner account in your country.
Example requests
The example below shows the request format for retrieving your default partner link. The API host and authentication headers are placeholders.
To sign and send this request, follow the Node.js example in Code Examples. Configure your API base URL, API key and signing key before running it.
GET /v1/partnership/partner/default-link HTTP/1.1
Host: <your-api-host>
EXN-API-KEY: <your-api-key>
EXN-TIMESTAMP: <fresh-unix-milliseconds>
EXN-SIGN-VERSION: 1
EXN-DATA: <base64url-signed-data>
EXN-SIGN: <base64url-signature>
What to expect in return
HTTP 200 returns the following illustrative response:
{
"full_default_link": "https://www.exness.com/a/demo22",
"domain": "www.exness.com",
"code": "demo22",
"path": "/a/demo22",
"url": "https://www.exness.com/a/demo22"
}
full_default_link and url contain your default partner link. The remaining fields provide its domain, referral code and path. These example values are illustrative; your response will contain your own link.
Troubleshooting common errors
| HTTP status / code | What It Means | How to Fix It |
|---|---|---|
429 / Throttled | A Partnership operation rate limit was exceeded. | Slow down the request rate and honor Retry-After when it is returned. |
504 / ServiceTransportError | A service required by the Partnership operation could not be reached or timed out. | Retry the request with exponential backoff. |
500 / Error | A Partnership operation failed because a required service could not complete the request. | Retry the request with backoff. |
401 / AuthenticationFailed | A Partnership service rejected the authenticated request after request authentication. API-key and request-signature failures use the numeric authentication errors. | Check the request authorization context. When the response uses the numeric envelope, follow the action for its error_message. |
403 / PermissionDenied | The authenticated identity cannot perform the operation or access the requested partner data. | Use credentials with the required Partnership permission and resource access. |
400 / ValidationError | Request validation failed, including bad-request or conflict conditions returned as validation errors. | Do not retry unchanged. Correct the request using details, then sign the corrected request again. |
502 / 1 — SYSTEM_BAD_GATEWAY | The API could not complete the request to the Partnership service. | Retry the request with backoff. |
503 / 2 — SYSTEM_TEMPORARY_UNAVAILABLE | A required service is temporarily unavailable or the request deadline was exceeded. | Retry the request with backoff. |
500 / 3 — SYSTEM_INTERNAL_ERROR | The API encountered an unexpected internal error. | Retry the request with backoff. |
401 / 1000 — AUTH_INVALID_API_KEY | The API key is invalid, expired, revoked, or not allowed for the request source. | Check the API key, its state, and its allowed source IP. |
401 / 1001 — AUTH_INVALID_SIGNATURE | The request signature or signed timestamp is invalid. | Rebuild the signature from the exact request and a fresh timestamp. |
403 / 1002 — AUTH_FORBIDDEN | The API key does not have a required operation scope. | Use an API key with the required Partnership scope. |
429 / 1003 — AUTH_RATE_LIMIT | The authentication rate limit was exceeded. | Honor Retry-After and reduce request rate. |
400 / 3001 — REQUEST_INVALID_PARAMETERS | Required headers or signed request data are malformed or inconsistent. | Correct the headers or signed values named by description, then sign the exact request again. |
Inspect the error envelope before choosing the next action. A numeric code uses error_message; a Partnership string code uses message and can include details. See Troubleshooting Your API Requests.