This guide outlines important concepts to consider when developing an integration with the Push Cash API.

​
Authentication

The API uses a persistent API key to authenticate requests. Provide the key using the Authorization header with the value Bearer YOUR_API_KEY. Requests that fail authentication return a 401 (Unauthorized) status code. In order to test your API keys, you can make a request to the /keys/verify endpoint in either sandbox or production 
curl -X POST -H "Authorization: Bearer $APIKEY" https://sandbox.pushcash.com/keys/verify
If the API key is valid, the API will respond with a status code of 200 (OK) and the name of your organization

​
Idempotency

Idempotency ensures that making the same request more than once won’t result in duplicate operations. This is helpful in cases like network retries or client timeouts. When a POST request is received, we determine if it’s a duplicate by comparing one of the following:
  • A custom header you provide (X-Idempotency-Key)
  • A unique field in the request body (e.g. tag, token)
  • The exact contents of the request body (if the same data was already processed)
If we detect a duplicate, we return the same response as the original request, and do not create the resource again.

​
Idempotency by Endpoint

EndpointIdempotency MechanismDescription
POST /usertag fieldRequests with the same tag return the same user.
POST /intentX-Idempotency-KeySet this header to uniquely identify each request.
POST /authorizetoken fieldThe token field prevents duplicate authorization attempts.

​
Best Practices

  • Use a consistent X-Idempotency-Key when retrying requests.
  • Ensure tag or token fields are unique for each new resource.
  • Don’t reuse idempotency keys across different request types.

​
Rate Limiting

The Push Cash API rate-limits requests to ensure stable and reliable service for all users. All rate limits are evaluated on a sliding 1 hour window. Requests subject to rate limiting will include the following response headers:
  • X-RateLimit-Limit: The maximum number of requests that can be made to the endpoint in a window.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • X-RateLimit-Reset: The time at which the current window will reset.
When a request exceeds the rate limit, the API will respond with a status code of 429 (Too Many Requests). Requests that are issued from your backend and authenticated with an API token are subject to the following rate limits:
  • Create: 100 requests
    • Creating new users, intents
  • Read: 1,000 requests
    • Getting or listing existing objects