Request Headers Guidelines

When making requests to the API, certain HTTP headers ensure that communication is reliable, predictable, and compliant with web standards.

📘

Applicative Headers

Headers directly related to your API request content and authentication.

Header	Purpose / Short Description
📦 Content-Type	Indicates format of request body (e.g., JSON).
🎯 Accept	Tells API which response format is expected (usually JSON).
🔑 Authorization	Provides API key / token for authenticated endpoints.
🛡️ Idempotency-Key	Optional; prevents duplicate operations on retry (critical for payments/payouts).

📘

Transport / HTTP Headers

Required or automatically handled by the HTTP protocol. Do not modify unless you know what you are doing.

Header	Purpose / Short Description
🖥️ Host	Identifies the server being contacted (required by HTTP/1.1).
📏 Content-Length	Size of request body in bytes (auto-calculated by client).
📝 User-Agent	Identifies client software; used for monitoring/debugging.
🔗 Connection	Controls if network connection remains open after request.

👍

Best practices

• Always send Content-Type: application/json when including a JSON body.
• Always send Accept: application/json to ensure consistent responses.
• Always include Authorization for secured endpoints.
• Use Idempotency-Key for critical operations to prevent duplicates.
• Let your HTTP client handle transport headers (Host, Content-Length, Connection) automatically.
• Log all request and response headers during development to simplify debugging.

---

🔒 Application-Level Headers (you must set them)

These headers directly affect how the API interprets your request and what it returns. You are responsible for setting them correctly.

Content-Type

Purpose: Tells the API how to interpret the body of your request.

Most common value:

HTTP

Content-Type: application/json

📘

Why it matters

• Without it, the API may not parse your request body correctly.
• Some endpoints may still work, but unexpected issues (e.g. malformed JSON errors) can appear.
• ✅Always set this header when sending JSON bodies (e.g. POST, PUT, PATCH requests).

---

Accept

Purpose: Tells the API the format you expect in the response.

Most common value:

HTTP

Accept: application/json

📘

Why it matters

• Ensures the API returns JSON.
• Without it, the server may default to another format (rare but possible).
• ✅ Always include Accept: application/json.

---

Authorization

Purpose: Carries your API key, token, or credentials.

Example:

HTTP

Authorization: Bearer YOUR_API_KEY

📘

Why it matters

• Required for all authenticated endpoints (all except "login").
• Without it, you will receive 401 Unauthorized.

---

Idempotency-Key (if supported)

Purpose: Prevents duplicate operations (e.g. payments, payouts) when retrying a request.

Example:

HTTP

Idempotency-Key: unique-string-123

📘

Why it matters

If your client retries due to a timeout or network issue, the API ensures the same operation is not executed twice.

---

⚙️ Transport-Level Headers (handled by HTTP clients)

These headers are required by the HTTP protocol itself. In almost all cases, your HTTP client (e.g. Postman, curl, axios, fetch) automatically sets them.

---

Host

• Identifies the server you are connecting to.
• Mandatory in HTTP/1.1.

Example:

HTTP

Host: api.example.com

⚠️ If you remove it manually, the server will likely return 400 Bad Request.

---

Content-Length

• Indicates the size (in bytes) of the request body.
• Automatically calculated and added by your HTTP client when you send a body.
• Incorrect values can cause truncated or rejected requests.
• ✅ Do not set it manually unless absolutely necessary.

---

User-Agent

Identifies your client software; user for monitoring/debugging.

Example values:

HTTP

PostmanRuntime/7.32.3
curl/8.1.2

Some APIs use it for monitoring or debugging.

✅Keep it, or set a custom value to identify your integration.

---

Connection

Controls whether the network connection stays open after the request.

Example value:

HTTP

Connection: keep-alive

Usually added automatically by the client. Rarely needs to be changed.