Source: https://databento.com/docs/api-reference-data/basics


## Basics


### Overview

Our reference API has the following structure:

- [Corporate actions](https://databento.com/docs/api-reference-data/corporate-actions.md) provides point-in-time (PIT) corporate actions events with global coverage.
- [Adjustment factors](https://databento.com/docs/api-reference-data/adjustment-factors.md) provides end-of-day price adjustment factors for capital events, spanning multiple currencies for the same event.
- [Security master](https://databento.com/docs/api-reference-data/security-master.md) provides up-to-date (latest) or point-in-time (PIT) static information on global market securities.


### Authentication

Databento uses API keys to authenticate requests. You can view and manage
your keys on the [API keys]($PLATFORM_HOSTNAME/portal/keys) page of your portal.

Each API key is a 32-character string starting with `db-`. By default, our library uses the
environment variable `DATABENTO_API_KEY` as your API key. However, if you
pass an API key to the `Reference` constructor through the `key` parameter,
then this value will be used instead.

Related: [Securing your API keys](https://databento.com/docs/portal/api-keys.md#securing-your-api-keys).

#### Example usage

```python
import databento as db

# Establish connection and authenticate
client = db.Reference("$YOUR_API_KEY")

# Authenticated request
print(client.security_master.get_last(symbols="AAPL"))
```


### Symbology

The reference datasets support querying by `raw_symbol` and additionally symbology types listed in the below table (depending on the endpoint).

The `raw_symbol` symbology type uses a standardized convention for the `symbols` parameter for requests.
This convention is referred to as the "Nasdaq Integrated Platform Suffix" and is used consistently across our datasets, regardless of the suffix originally used by the exchange.

- **Standardization.** This approach aligns with our symbology standardization for US equity datasets. For a detailed explanation, see our [symbology standards](https://databento.com/docs/conventions/symbology.md) documentation.
- **Local Codes.** The `local_code` field retains the original symbol from the primary exchange. For example, symbols from NYSE-owned feeds such as NYSE Texas use the "CMS Suffix".

For additional context on symbol conventions, including the four most common suffix patterns used for US equities, refer to [Nasdaq's guide on ticker symbol conventions](https://www.nasdaqtrader.com/trader.aspx?id=CQSsymbolconvention).

The symbology related fields included with every data record are as follows:

| Field | Description |
| `nasdaq_symbol` | Nasdaq Integrated Platform Suffix convention symbol (standardized `raw_symbol`). |
| `local_code` | Local code, typically the original symbol and unique at the listing level (but there are exceptions to this rule). Either an alpha string, or a number. |
| `isin` | [**I**nternational **S**ecurities **I**dentification **N**umber (ISIN)](https://www.isin.org/) - ISO 6166. |
| `us_code` | US domestic [**C**ommittee on **U**niform **S**ecurities **I**dentification **P**rocedure (CUSIP)](https://en.wikipedia.org/wiki/CUSIP) code. |
| `bbg_comp_id` | Bloomberg composite global ID. |
| `bbg_comp_ticker` | Bloomberg composite ticker. |
| `figi` | **F**inancial **I**nstrument **G**lobal **I**dentifier (FIGI), formerly Bloomberg Global Identifier (BBGID). Listing level identifier. |
| `figi_ticker` | Bloomberg exchange-level ticker. |
| `listing_id` | Databento-specific identifier that tracks an individual exchange's listing of a security. |
| `issuer_id` | Databento-specific identifier shared across all securities issued by the same company. |
| `security_id` | Databento-specific identifier at the security level, tracking a security across all of its exchange listings. |

> **Info**
>
> Note a symbol may match multiple securities across a time range if the symbol has been recycled.

> **Tip**
>
> When identifying a listing on a specific venue, we suggest using the `nasdaq_symbol` field, as it aligns
> with the normalized `raw_symbol` for instruments. Once you have the ISIN for the security, using
> the `isin` symbology type will provide the most accurate results when querying for related records.


### Dates and times

Our Python client library has several functions with timestamp arguments. These arguments will have type `pandas.Timestamp | datetime.date | str | int` and support a variety of formats.

It's recommended to use [pandas.Timestamp](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html), which fully supports timezones and nanosecond-precision. If a `datetime.date` is used, the time is set to midnight UTC. If an `int` is provided, the value is interpreted as [UNIX nanoseconds](https://en.wikipedia.org/wiki/Unix_time).

The client library also handles several string-based timestamp formats based on [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).

- `yyyy-mm-dd`, e.g. `"2022-02-28"` (midnight UTC)
- `yyyy-mm-ddTHH:MM`, e.g. `"2022-02-28T23:50"`
- `yyyy-mm-ddTHH:MM:SS`, e.g. `"2022-02-28T23:50:59"`
- `yyyy-mm-ddTHH:MM:SS.NNNNNNNNN`, e.g. `"2022-02-28T23:50:59.123456789"`

Timezone specification is also supported.

- `yyyy-mm-ddTHH:MMZ`
- `yyyy-mm-ddTHH:MM±hh`
- `yyyy-mm-ddTHH:MM±hhmm`
- `yyyy-mm-ddTHH:MM±hh:mm`

**Bare dates**

Some parameters require a bare date, without a time. These arguments have type `datetime.date | str` and must either be a `datetime.date` object, or a string in `yyyy-mm-dd` format, e.g. `"2022-02-28"`.


### Errors

Our reference API uses HTTP response codes to indicate the success or
failure of an API request. The client library provides exceptions that
wrap these response codes.

- `2xx` indicates success.
- `4xx` indicates an error on the client side. Represented as a `BentoClientError`.
- `5xx` indicates an error with Databento's servers. Represented as a `BentoServerError`.

The full list of the response codes and associated causes is as follows:

| Code | Message | Cause |
| 200 | OK | Successful request. |
| 400 | Bad Request | Invalid request. Usually due to a missing, malformed or unsupported parameter. |
| 401 | Unauthorized | Invalid username or API key. |
| 403 | Forbidden | The API key has insufficient permissions to perform the request. |
| 404 | Not Found | A resource is not found, or a requested symbol does not exist. |
| 422 | Unprocessable Entity | The request is well formed, but we cannot or will not process the contained instructions. |
| 429 | Too Many Requests | API rate limit exceeded. |
| 500 | Internal Server Error | Unexpected condition encountered in our system. |
| 503 | Service Unavailable | Data gateway is offline or overloaded. |
| 504 | Gateway Timeout | Data gateway is available but other parts of our system are offline or overloaded. |

#### API method

```python
class databento.BentoError(Exception)
class databento.BentoHttpError(databento.BentoError)
class databento.BentoClientError(databento.BentoHttpError)
class databento.BentoServerError(databento.BentoHttpError)
```

#### Example usage

```python
import databento as db

client = db.Reference("INVALID_API_KEY")

try:
    print(client.security_master.get_last("TEST"))
except db.BentoClientError as e:
    print(e)
```
#### Example response

```plaintext
400 auth_invalid_username_in_basic_auth
Invalid username in Basic auth ('INVALID_API_KEY').
documentation: https://databento.com/docs
```


### Rate limits

Our reference API allows each IP address up to:
- 100 concurrent connections.
- 100 [corporate actions](https://databento.com/docs/api-reference-data/corporate-actions.md) requests per second.
- 100 [adjustment factors](https://databento.com/docs/api-reference-data/adjustment-factors.md) requests per second.
- 100 [security master](https://databento.com/docs/api-reference-data/security-master.md) requests per second.

When a request exceeds a rate limit, a `BentoClientError` exception is raised
with a 429 error code.

**Retry-After**

The Retry-After response header indicates how long the user should wait before retrying.

If you find that your application has been rate-limited, you can retry after waiting for the time specified in the Retry-After header.

If you are using Python, you may use the time.sleep function as seen below to wait for the time specified in the Retry-After header.
e.g. `time.sleep(int(response.headers("Retry-After", 1)))`

This code snippet works best for our current APIs with their rate limits. Future APIs may have different rate limits, and might require a different default time delay.