> For the complete documentation index, see [llms.txt](https://docs.papayaglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.papayaglobal.com/api-reference/api-essentials.md).

# API Essentials

The Papaya Global Workforce Payments API is organized around REST. The API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

#### **HTTP Methods** <a href="#apiessentials-httpmethods" id="apiessentials-httpmethods"></a>

The Workforce Payments API uses HTTP methods to perform operations on resources. The most commonly used methods are:

<figure><img src="/files/uYSPfgi8eoAfTB51yQkJ" alt=""><figcaption></figcaption></figure>

#### **Data Types** <a href="#apiessentials-datatypes" id="apiessentials-datatypes"></a>

The Workforce Payments API consistently utilizes data types and formats.

| Data Types     | Description                                                                                  | Sample Use Cases                                                                     | Sample Values                    |
| -------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------- |
| Dates          | Dates are represented in the YYYY-MM-DD format without any time or timezone information      | `date_of_birth`                                                                      | `1970-01-01`                     |
| Time Stamps    | The format for representing date and time with timezone information is YYYY-MM-DDTHH:mm:ssZ. | <p><code>start\_date</code></p><p><code>end\_date</code></p><p><code>date</code></p> | `2024-03-02T09:09:51.508859936Z` |
| Country Codes  | Country codes in the ISO 3166-2 standard consist of two letters.                             | <p><code>address\_country</code></p><p><code>account\_country</code></p>             | `AU`                             |
| Currency Codes | Currency code in ISO 4217 with three letters.                                                | `currency`                                                                           | `AUD`                            |

#### **Response Codes** <a href="#apiessentials-responsecodes" id="apiessentials-responsecodes"></a>

The Papaya Global Workforce Payments API utilizes standard HTTP response codes to communicate the outcome of an API request. A status code falling within the 2xx range signifies success, while codes in the 4xx range point to errors caused by the input data (e.g., invalid parameters or missing information). Conversely, status codes in the 5xx range signal a server-related error.

| HTTP Status Codes                                    | Response Indication   | Description                                                                                                                                                      |
| ---------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="background-color:green;">**200**</mark> | OK                    | The request has been successfully handled.                                                                                                                       |
| <mark style="background-color:green;">**201**</mark> | Created               | The request has been successfully processed, resulting in the creation of a new resource.                                                                        |
| <mark style="background-color:green;">**202**</mark> | Accepted              | The request has been approved for processing, however, the processing is still ongoing. The request's completion is uncertain until the processing is finalized. |
| <mark style="background-color:red;">**400**</mark>   | Bad Request           | The request lacks essential parameters, is in an improper format, or did not pass another validation test.                                                       |
| <mark style="background-color:red;">**401**</mark>   | Unauthorized          | The authentication token has been provided and is in a valid state.                                                                                              |
| <mark style="background-color:red;">**402**</mark>   | Request Failed        | Financial transaction was declined. Parameters were valid but request failed.                                                                                    |
| <mark style="background-color:red;">**403**</mark>   | Forbidden             | The web server acknowledges the request but declines to authorize it due to permission issues.                                                                   |
| <mark style="background-color:red;">**404**</mark>   | Not Found             | The specified endpoint is not available.                                                                                                                         |
| <mark style="background-color:red;">**405**</mark>   | Method Not Allowed    | The HTTP request sent by your browser is not permitted for the specified resource or URL.                                                                        |
| <mark style="background-color:red;">**429**</mark>   | Too Many Requests     | Indicates the user has sent too many requests in a given amount of time ("rate limiting").                                                                       |
| <mark style="background-color:red;">**500**</mark>   | Internal Server Error | The server has encountered an unforeseen circumstance that has hindered its ability to fulfill the request.                                                      |

#### **Errors Response** <a href="#apiessentials-errorsresponse" id="apiessentials-errorsresponse"></a>

The body of the Global Workforce Payments API error response typically includes the following fields:

| Attribute   | Type   | Description                                                                                                         |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| Error       | String | Represents the high-level error message.                                                                            |
| Description | String | Provides a detailed description of the error.                                                                       |
| Error Code  | String | Specifies the HTTP error code or any custom error code associated with the error.                                   |
| Sub Code    | String | Optionally provides additional sub-codes for categorizing specific types of errors under the same high-level error. |

**Response** **Examples** **with Sub Code**

```json
{
  "error": "Error Message",
  "description": "Failed calling service",
  "error_code": "Error Code",
  "sub_code": "Sub Code",
  "error_info": { // Example for HTTP error
    "timestamp": "Timestamp",
    "status": "HTTP Status Code",
    "error": "Error Message",
    "path": "Request Path"
  }
}
```

```json
{
  "error": "not_found",
  "description": "Wallet not found",
  "error_code": 404,
  "sub_code": 1000,
  "error_info": {
    "timestamp": "2024-03-04T07:55:43.543Z",
    "status": 404,
    "error": "The specified wallet ID does not exist.",
    "path": "/v1/wallet"
  }
}
```

**Response** **Examples** **without Sub Code**

```json
{
  "error": "Error Message",
  "description": "Failed calling service",
  "error_code": "Error Code"
```

```json
{
  "error_code": 401, 
  "error": "Unauthorized", 
  "description": "Authorization failed. The server could not verify your credentials. Please check your configuration and try again."
}
```

#### Rate Limits <a href="#apiessentials-ratelimits" id="apiessentials-ratelimits"></a>

To ensure a responsive and fair usage environment for all our users, we enforce rate limits on our REST API. Each endpoint has an assigned request limit carefully calibrated to balance frequent access with system integrity and equitable resource distribution.

* **Standard Rate Limit**: Our standard rate limit is **500 requests per minute** per authenticated user. This applies to most endpoints unless otherwise specified.

{% hint style="info" %}
The rate limit is determined by the number of calls made, not the number of actions taken. Therefore, calling the bulk endpoints enables more actions to be performed within the rate limit.
{% endhint %}

* **Extended Limits**: Higher rate limits may be available depending on your subscription tier or upon request for specific use cases that require more frequent access.
* **Headers and Feedback**: Every API response includes HTTP headers that provide your current rate limit status:
  * `X-RateLimit-Limit`: The maximum number of requests permitted within the window.
  * `X-RateLimit-Remaining`: The remaining number of requests within the current rate limit window.
  * `X-Ratelimit-Used`: The total amount of requests you have made during the current rate limit interval.
  * `X-RateLimit-Reset`: When the current rate limit window resets in UTC epoch seconds.
  * `X-Ratelimit-Resource`: The resource against which the request was counted for rate-limiting purposes.
* **Best Practices**: We recommend implementing retry logic with exponential backoff and respecting the `Retry-After` header where applicable. This approach aids in efficiently utilizing rate limits and reduces the likelihood of encountering limits.
* **Exceeding Limits**: Attempts to exceed rate limits will result in a `429 Too Many Requests` response. Continuous overage may lead to temporary or permanent suspension of API access. We urge all users to architect their applications to handle such responses gracefully.
* **Changes and Notifications**: Rate limits are subject to change based on system performance and user demand. All changes will be communicated through our developer channels and API change log.&#x20;