# General

## Authentication

All API requests need to be authenticated. To do this, you need to always send the HTTP header `Authorization` with your API key as a bearer token:

`Authorization: Bearer your_api_key`

## Rate limits

To protect our servers from getting overloaded and avoid misuse, we enforce a rate limit of 100 requests per minute. You shouldn't need to poll frequently for status updates as you can get real-time updates via [Webhooks](/reference/api-reference/webhooks.md). In case you have a valid use case for a higher rate limit, please contact your account manager.

The API responds with the following headers to indicate the number of requests used and the maximum available:

```
X-Rate-Limit-Used: 42
X-Rate-Limit-Max: 100
```

Any requests above the limit will be denied with a 429 response code (too many requests). In that case, the response also includes an extra header which shows how many seconds you need to wait before sending a new request:

```
Retry-After: 3.2
```

## Errors

When a request is unsuccessful, you will get an HTTP status code of [4xx (for client errors)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses) or [5xx (for server errors)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses). The body then will always contain an `errors` property which contains an array of human-readable errors. 

### Common errors

If your API key is missing, or wrong, you'd get a 401 Unauthorized with this JSON response:

```json
{
  "success": false,
  "errors": [
    "authentication required"
  ]
}
```

Another example, when the request is malformed, you'd get a 400 Bad request:

```json
{
  "success": false,
  "errors": [
    "bad request"
  ]
}
```

Finally, if the data is not valid, you'd get a 422 Unprocessable Entity:

```json
{
  "success": false,
  "errors": [
    "Name can't be blank",
    "Merchant sku can't be blank"
  ]
}
```

## Successful responses

When an API request is successful, you will get an HTTP status code of [2xx](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses). The response body will either be a single object or a collection of objects.

### Single object

When you create or update an object, you will get the final state of the object in the response:

```json
{
    "id": 34,
    "merchant_sku_id": "HIVE_TSH_BLK_M",
    "name": "Hive T-Shirt (Black - M)",
    "created_at": "2022-08-10T17:53:04.438+02:00",
    "cost_in_cents": null,
    "country_code_of_origin": null,
    "hs_code": null,
    "weight_in_kg": 0.3,
    "inventory": {
        "stocked": 10000,
        "reserved": 0,
        "total": 10000
    }
}
```

### Collection of objects

When you get a collection of objects in the response, the response is an object with a `data` property and a `pagination` property. The actual collection of object is in the `data` property:

```json
{
  "data": [
    {
      "id": 9,
      "merchant_sku_id": "2218061549136",
      "name": "Morph II",
      "created_at": "2022-08-10T17:53:04.822+02:00",
      "cost_in_cents": null,
      "country_code_of_origin": null,
      "hs_code": null,
      "weight_in_kg": 45.37,
      "inventory": {
        "stocked": 10000,
        "reserved": 0,
        "total": 10000
      }
    },
    {
      "id": 4,
      "merchant_sku_id": "4976808834423",
      "name": "Mr Moonstone",
      "created_at": "2022-08-10T17:53:04.507+02:00",
      "cost_in_cents": null,
      "country_code_of_origin": null,
      "hs_code": null,
      "weight_in_kg": 24.92,
      "inventory": {
        "stocked": 10000,
        "reserved": 0,
        "total": 10000
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "item_count": 2,
    "page_count": 1,
    "items_per_page": 20
  }
}
```

### Pagination

In order to access all the objects of the collection, you need to send multiple requests to an endpoint. This works by adding the query string parameter `page` to the URL (e.g. <https://app.hive.app/merchant_api/v1/skus?page=2>).&#x20;

The `pagination.page_count` property of the response, returns how many pages are available. If no page parameter is provided, it defaults to `1` (that is, the first page of results).

The number of objects per page is configured by passing a `limit` in the query parameters (e.g. <https://app.hive.app/merchant_api/v1/skus?limit=50>). A maximum of `100` is enforced. The default is `20` if it's not provided.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.hive.app/reference/api-reference/general.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.