> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heydollr.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API Conventions

> Base URL, JSON format, validation errors, and HTTP status codes for the Dollr API.

## Base URL and versioning

All endpoints use the `v1` prefix:

```
https://api.heydollr.app/v1/<resource>
```

See [Environments](/reference/environments) for credentials and testing guidance.

## Request format

* **Content-Type:** `application/json` for requests and responses
* **Timestamps:** ISO 8601 (e.g. `2025-06-01T14:30:00Z`)
* **Currency:** ISO 4217, uppercase (e.g. `USD`, `LRD`)
* **Phone:** E.164 digits **without** `+` (e.g. `231771234567`)
* **Amounts:** Positive numbers; minimum `0.01` for decimals, `1` for integers
* **`reference_id`:** Version-4 UUID on every execution (idempotency key)

## Resource ID types

Some fields accept the same logical ID in different JSON types depending on the endpoint:

| Field                | Endpoint                            | JSON type             | Example |
| -------------------- | ----------------------------------- | --------------------- | ------- |
| `session_id`         | `POST /v1/executions/*`             | **string**            | `"55"`  |
| `session_id`         | `POST /v1/realtime-keys/collection` | **integer**           | `55`    |
| `payment_account_id` | Executions                          | **string**            | `"18"`  |
| `payout_account_id`  | Sessions / executions               | **integer** or number | `18`    |
| `source_id`          | Sessions, status, predictions       | **integer**           | `101`   |

When in doubt, match the type shown in [API Reference](/api-reference/sessions/create-checkout-session) for that specific endpoint.

## `source_kind` vs `source_type`

A frequent source of **422** errors:

| Context                              | Field name    | Used on                                                     |
| ------------------------------------ | ------------- | ----------------------------------------------------------- |
| Creating checkout source             | `source_kind` | `POST /v1/checkouts/create`                                 |
| Sessions, status, links, predictions | `source_type` | `POST /v1/sessions/checkout`, `GET /v1/status/source`, etc. |

**Values are the same:** `INVOICE` or `ORDER`.

```json theme={null}
// Checkouts create
{ "source_kind": "INVOICE" }

// Checkout session
{ "source_type": "INVOICE", "source_id": 101 }
```

`SUBSCRIPTION` appears in some OpenAPI enums but is **not publicly supported** yet.

## Validation errors (422)

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "currency"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

Inspect the `detail` array for field-level messages.

## HTTP status codes

| Code  | Meaning          | Typical action                   |
| ----- | ---------------- | -------------------------------- |
| `200` | Success          | Use response body                |
| `401` | Unauthorized     | Refresh JWT                      |
| `403` | Forbidden        | Check verification / permissions |
| `404` | Not found        | Verify resource ID               |
| `422` | Validation error | Fix payload per `detail`         |
| `429` | Rate limited     | Back off; honor `Retry-After`    |
| `5xx` | Server error     | Retry with exponential backoff   |

## Related

* [Authentication](/authentication)
* [Currency & FX](/concepts/currency-and-fx)
* [Error handling](/guides/error-handling)
* [Error catalog](/reference/error-catalog)