Headers, Idempotency and Errors

This guide explains the request headers, idempotency rules, retry behavior, and error handling conventions that partner applications should implement.

Use this host in all examples:

https://api.yes.cash

---

1. Required headers

1.1 Anonymous Auth API calls

Use this pattern before the customer has an access token.

POST https://api.yes.cash/v1/auth/start
Content-Type: application/json
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>

Required headers:

---

1.2 Customer-authenticated API calls

Use this pattern after login, registration, or token refresh.

GET https://api.yes.cash/v1/core/profile
Authorization: Bearer <access-token>
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>

Required headers:

---

1.3 Idempotent action calls

Use Idempotency-Key for retryable business actions.

POST https://api.yes.cash/v1/core/transfers/{transferId}/submit
Authorization: Bearer <access-token>
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>
Idempotency-Key: <uuid>
Content-Type: application/json

Use idempotency keys for operations such as:

• quote acceptance;
• transfer submission;
• transfer confirmation;
• transfer cancellation;
• beneficiary creation, where supported;
• funding-session creation, where supported.

Do not reuse the same Idempotency-Key for different business actions.

---

2. Header reference

---

3. Correlation IDs

X-Correlation-Id is used for tracing.

The partner app should:

• generate a UUID for each API request, or for each business journey;
• log the correlation ID in partner-side logs;
• show the correlation ID in support/debug screens if appropriate;
• include the correlation ID when contacting YesCash support.

Example:

X-Correlation-Id: 5e4f3c72-4c3c-46e5-82e6-5a7c6d7218af

Recommended pattern:

---

4. Idempotency keys

An idempotency key protects the customer and partner app from duplicate business actions when a request is retried.

4.1 When to use

Use an idempotency key when the API call changes state or may create a financial/business action.

Examples:

Accept quote
Submit transfer
Confirm transfer
Cancel transfer
Create beneficiary
Start funding session

4.2 When not to use

Usually not needed for:

GET /v1/core/profile
GET /v1/core/transfers/{transferId}
GET /v1/core/transfers
GET /v1/core/beneficiaries

4.3 Key format

Use UUID v4.

Idempotency-Key: b3f077a8-2930-4555-91ac-4ad6d5dbf51d

4.4 Reuse rule

Use the same idempotency key when retrying the same business action.

Do not use the same key for a different action.

Correct:

First transfer submit attempt → Idempotency-Key A
Retry same transfer submit    → Idempotency-Key A

Incorrect:

Transfer submit               → Idempotency-Key A
Transfer cancellation          → Idempotency-Key A

4.5 Retry after timeout

If the partner app sends a request and receives no response because of a timeout:

1. retry the same request;

2. use the same Idempotency-Key;

3. do not create a new business action until the API confirms the final state.

---

5. Standard error response

Errors are returned as structured JSON.

Typical shape:

{
  "error": {
    "code": "quote.expired",
    "message": "The quote has expired.",
    "hint": "hint.partner_app.refresh_quote",
    "remediation": "remediation.customer_ux.refresh_quote"
  },
  "correlationId": "5e4f3c72-4c3c-46e5-82e6-5a7c6d7218af"
}

Partner apps should build logic around:

Do not rely on exact English message text for application logic. Use error.code.

---

6. Error handling principles

Partner apps should follow these rules:

• Use error.code for branching logic.
• Treat unknown error codes safely.
• Show customer-friendly messages, not raw technical errors.
• Log the full error response.
• Include correlationId in support tickets.
• Do not expose security-sensitive detail to customers.
• Do not repeatedly retry non-retryable validation errors.

---

7. Common Auth errors

---

8. Common Core API errors

Exact error availability depends on the endpoint. Always check the OpenAPI reference for endpoint-specific errors.

---

9. Retry guidance

9.1 Safe to retry

Usually safe to retry with backoff:

9.2 Do not blindly retry

Do not repeatedly retry:

---

10. Recommended exponential backoff

For retryable technical failures:

Attempt 1: immediate retry only if safe
Attempt 2: wait 1 second
Attempt 3: wait 2 seconds
Attempt 4: wait 5 seconds
Stop and show recoverable error

For money-moving actions, always retry with the same Idempotency-Key.

---

11. Token expiry handling

Partner apps should not wait for every token to fail.

Recommended behavior:

1. track access-token expiry locally if available;

2. refresh shortly before expiry;

3. if an API call returns auth.tokenExpired, call /v1/auth/refresh;

4. retry the original request with the new token;

5. if refresh fails, clear session and send customer to login.

Example flow:

API returns auth.tokenExpired
  → POST /v1/auth/refresh
  → receive new access token
  → retry original request

---

12. Quote expired handling

If quote acceptance fails with quote.expired:

1. do not retry the same acceptance request;

2. request or generate a new quote;

3. show the new pricing to the customer;

4. ask the customer to accept again;

5. submit acceptance using a new idempotency key for the new quote.

---

13. Idempotency conflict handling

If the API returns an idempotency conflict:

1. check whether the same key was reused with a different request body;

2. do not keep retrying the conflicting request;

3. fetch the latest resource state where possible;

4. create a new idempotency key only if the customer is starting a new action.

Example:

Same transfer submit request retried with same key → correct
Different transfer submit request with same key    → conflict

---

14. Not found behavior

For security and data isolation, 404 can mean:

• the resource does not exist;
• the resource exists but is not available to the current customer session;
• the resource is no longer usable.

Partner app behavior:

• do not tell the customer that a hidden resource exists;
• refresh the relevant list;
• show a neutral message such as "We could not find this item. Please refresh and try again."

---

15. Customer-facing message guidance

Partner apps should convert technical errors into simple customer messages.

---

16. Logging checklist

Partner systems should log:

• timestamp;
• endpoint;
• HTTP method;
• HTTP status;
• X-Correlation-Id;
• idempotency key, if used;
• customer app session reference, if available;
• error code;
• non-sensitive request context.

Do not log:

• passwords;
• OTP values;
• access tokens;
• refresh tokens;
• device private keys;
• full payment instrument data;
• sensitive identity document images.

---

17. Support checklist

When escalating an API issue to YesCash support, provide:

• environment;
• endpoint;
• HTTP method;
• timestamp with timezone;
• X-Correlation-Id;
• idempotency key, if relevant;
• HTTP status code;
• error code;
• short description of the customer action;
• sanitized request and response body, if needed.

Never send:

• customer password;
• OTP;
• full token values;
• device private keys;
• full card or bank sensitive data.

---

18. Implementation checklist

Before certification, confirm that the partner app:

• sends the subscription key on all API calls;
• sends bearer token on customer-authenticated calls;
• sends correlation IDs;
• uses idempotency keys for retryable business actions;
• retries safely with the same idempotency key after timeouts;
• refreshes expired access tokens;
• does not parse tokens for authorization decisions;
• handles quote expiry;
• handles KYC-required flows;
• handles device-registration-required flows;
• handles not-found responses neutrally;
• logs correlation IDs and error codes;
• avoids logging sensitive values.