# Get SKU
Source: https://developers.firstbase.com/api-reference/catalog/get-sku

/openapi.json get /api/v1/catalog/skus/{skuId}
Returns pricing and availability details for a single SKU available to the caller's organization. Returns 404 if the SKU does not exist or is not available to this organization.



# List brands
Source: https://developers.firstbase.com/api-reference/catalog/list-brands

/openapi.json get /api/v1/brands
Returns the list of brands available for asset creation. Use the brand code when creating assets with category_code. Optionally filter by code, name (case-insensitive partial match), or active status.



# List categories
Source: https://developers.firstbase.com/api-reference/catalog/list-categories

/openapi.json get /api/v1/categories
Returns the list of product categories available for asset creation. Use the category code when creating assets without a specific SKU. Optionally filter by code, name (case-insensitive partial match), or active status.



# List SKUs
Source: https://developers.firstbase.com/api-reference/catalog/list-skus

/openapi.json get /api/v1/catalog/skus
Returns a paginated list of SKUs (stock-keeping units) available to the caller's organization for ordering. Each SKU represents a purchasable product variant with pricing and availability information. Optionally filter by category code (e.g. COMPUTER, MONITOR, HEADSET) to narrow results.



# Create inventory level
Source: https://developers.firstbase.com/api-reference/inventory-levels/create-inventory-level

/openapi.json post /api/v1/inventory-levels
Creates an inventory level configuration that defines the minimum and maximum stock thresholds for a specific SKU at a specific warehouse. Optionally scoped to a region. Returns 409 if a level already exists for the same SKU + warehouse + region combination.



# Delete inventory level
Source: https://developers.firstbase.com/api-reference/inventory-levels/delete-inventory-level

/openapi.json delete /api/v1/inventory-levels/{id}
Soft-deletes (deactivates) an inventory level configuration. The record is not permanently removed; reactivation requires creating a new configuration via POST.



# List inventory levels
Source: https://developers.firstbase.com/api-reference/inventory-levels/list-inventory-levels

/openapi.json get /api/v1/inventory-levels
Returns a paginated list of inventory level configurations (min/max stock rules) for the caller's organization. Each record defines the minimum and maximum quantity thresholds for a specific SKU at a specific warehouse. Supports filtering by SKU, warehouse, region, category, brand, and active status.



# Update inventory level
Source: https://developers.firstbase.com/api-reference/inventory-levels/update-inventory-level

/openapi.json patch /api/v1/inventory-levels/{id}

        Partial update for inventory level thresholds and reordering settings.

        Fields accepted: minQuantity, maxQuantity, includeUsed, autoCreate, active, customerPoNumber.

        skuId, warehouseId, and regionId are NOT accepted (immutable after creation) — sending
        any of them returns 400 with a per-field error message. Any other field name returns
        400 'Unknown field: <name>'. Sending an empty body returns 400 'At least one modifiable
        field must be provided'.

        Setting active=false soft-deletes the level. Reactivating via PATCH (active=true on an
        inactive level) is not supported; use POST /api/inventory-levels. Sending active=true
        on an already-active level is a 200 no-op (no state change, no write).
    



# Cancel inventory order
Source: https://developers.firstbase.com/api-reference/inventory-orders/cancel-inventory-order

/openapi.json delete /api/v1/inventory-orders/{inventoryOrderId}
Cancels an inventory order. Allowed only when the order is in SUBMITTED status.



# Create inventory order
Source: https://developers.firstbase.com/api-reference/inventory-orders/create-inventory-order

/openapi.json post /api/v1/inventory-orders
Creates an inventory order to ship equipment from a supplier or customer to a Firstbase warehouse. Specify the destination warehouse and the items (SKUs with quantities) to be stocked. The created order begins in SUBMITTED status and will be processed by the Firstbase logistics team.



# Get inventory order
Source: https://developers.firstbase.com/api-reference/inventory-orders/get-inventory-order

/openapi.json get /api/v1/inventory-orders/{id}
Returns a single inventory order (including items and shipments) belonging to the caller's organization.



# List inventory orders
Source: https://developers.firstbase.com/api-reference/inventory-orders/list-inventory-orders

/openapi.json get /api/v1/inventory-orders
Returns a paginated list of inventory orders (warehouse stock replenishment requests) for the caller's organization. Supports filtering by status and date range, and sorting by creation date. Each result includes the ordered items and their shipment details.



# Modify inventory order
Source: https://developers.firstbase.com/api-reference/inventory-orders/modify-inventory-order

/openapi.json patch /api/v1/inventory-orders/{inventoryOrderId}
Partially update an inventory order. Field writability depends on order status — see request body schema.



# Add tags
Source: https://developers.firstbase.com/api-reference/inventory/add-tags

/openapi.json post /api/v1/inventory/{inventoryId}/tags
Adds one or more tags to an inventory item. Tags are key-value labels used to organize and filter inventory. Existing tags with the same key are not replaced — duplicates are ignored.



# Create asset
Source: https://developers.firstbase.com/api-reference/inventory/create-asset

/openapi.json post /api/v1/assets
Creates a new asset (inventory item) in the organization's inventory. Identify the product either by sku_id (for known SKUs) or by category_code + description (for custom products). Assign the asset to a person (person_id) or an office (office_id).



# Get inventory item
Source: https://developers.firstbase.com/api-reference/inventory/get-inventory-item

/openapi.json get /api/v1/inventory/{inventoryId}
Returns full details for a single inventory item belonging to the caller's organization. Returns 400 if the inventory does not belong to the organization.



# List inventory
Source: https://developers.firstbase.com/api-reference/inventory/list-inventory

/openapi.json get /api/v1/inventory
Returns a paginated list of inventory items owned by the caller's organization. Supports filtering by deploy status, person, office, category, and more. Results are sorted by creation date descending by default. Deprecated deploy statuses (GIFTED, LOCKED, OUT_FOR_REPAIR) are rejected with 400.



# Remove tag
Source: https://developers.firstbase.com/api-reference/inventory/remove-tag

/openapi.json delete /api/v1/inventory/{inventoryId}/tags/{tagId}
Removes a single tag from an inventory item. Idempotent for missing tags is not guaranteed; a missing item returns 404.



# Update inventory
Source: https://developers.firstbase.com/api-reference/inventory/update-inventory

/openapi.json patch /api/v1/inventory/{inventoryId}
Partially updates inventory attributes for a single item owned by the caller's organization. Only fields present in the body are changed.



# Create ITAD requests
Source: https://developers.firstbase.com/api-reference/itad/create-itad-requests

/openapi.json post /api/v1/itad/requests
Create ITAD requests from a list of inventory IDs. Items are automatically grouped by warehouse, creating one request per warehouse.



# Get ITAD request
Source: https://developers.firstbase.com/api-reference/itad/get-itad-request

/openapi.json get /api/v1/itad/requests/{requestId}
Returns full details for a single IT Asset Disposition (ITAD) request belonging to the caller's organization, including all items in the request and their individual disposition statuses.



# List eligible assets
Source: https://developers.firstbase.com/api-reference/itad/list-eligible-assets

/openapi.json get /api/v1/itad/eligible-assets
List inventory assets eligible for ITAD disposition. Eligibility is based on category, deploy status, and other criteria.



# List ITAD requests
Source: https://developers.firstbase.com/api-reference/itad/list-itad-requests

/openapi.json get /api/v1/itad/requests
Returns a paginated list of ITAD (IT Asset Disposition) requests for the organization. Each request represents a scheduled disposition event for one or more inventory items. Use query parameters to filter by status or date range.



# Get new joiner stats
Source: https://developers.firstbase.com/api-reference/new-joiners/get-new-joiner-stats

/openapi.json get /api/v1/new-joiners/stats
Aggregate counts for status cards and provisioning outcomes. Accepts the same filter query parameters as the list endpoint (e.g. countryCodes, equipmentReadiness, urgency) so stats reflect the filtered cohort. When startDateFrom is omitted, the domain applies a default 60-day lookback floor — supply it explicitly to widen the window beyond 60 days. Pagination and sort query parameters accepted on the list endpoint are ignored on this endpoint. Example: ?countryCodes=US&equipmentReadiness=NOT_STARTED



# List new joiners
Source: https://developers.firstbase.com/api-reference/new-joiners/list-new-joiners

/openapi.json get /api/v1/new-joiners
Paginated, filterable, sortable list of new joiner rows for the organization. When startDateFrom is omitted, the domain applies a default 60-day lookback floor — supply it explicitly to widen the window beyond 60 days.



# Send reminder
Source: https://developers.firstbase.com/api-reference/new-joiners/send-reminder

/openapi.json post /api/v1/new-joiners/{personId}/remind
Sends a reminder email to the specified new joiner. Optionally records the sender person for audit purposes.



# Get office
Source: https://developers.firstbase.com/api-reference/offices/get-office

/openapi.json get /api/v1/offices/{id}
Returns full details for a single office belonging to the caller's organization.



# List offices
Source: https://developers.firstbase.com/api-reference/offices/list-offices

/openapi.json get /api/v1/offices
Returns a paginated list of offices belonging to the caller's organization. Supports pagination. Active and inactive offices are both returned unless filtered.



# Modify office
Source: https://developers.firstbase.com/api-reference/offices/modify-office

/openapi.json patch /api/v1/offices/{officeId}
Partially update an office. Modifiable fields: `name`, `contactName`, `address` (full-object replace when present), `active`. Setting `active=false` soft-deletes the office. Reactivation (`active=true`) is not supported and returns 400. Business-rule rejections (active inventory, active return orders, default-office-for-package) return HTTP 409 with `source="office"` envelope.



# Approve order
Source: https://developers.firstbase.com/api-reference/orders/approve-order

/openapi.json post /api/v1/orders/{orderId}/approve
Transitions an order from AWAITING_APPROVAL to APPROVED status. Optionally accepts an approvedByPersonId to record who approved the order. Sends an approval notification email for person orders.



# Create order
Source: https://developers.firstbase.com/api-reference/orders/create-order

/openapi.json post /api/v1/orders
Places a new order for one or more SKUs, delivered to either a person or an office. Exactly one of `personId` or `officeId` must be provided. Shipping address is auto-resolved from the recipient when not explicitly supplied. Returns the newly created order, including its ID and initial status.



# Decline an order awaiting approval
Source: https://developers.firstbase.com/api-reference/orders/decline-an-order-awaiting-approval

/openapi.json post /api/v1/orders/{orderId}/decline
Rejects an order that is awaiting approval. Transitions AWAITING_APPROVAL → DECLINED. All non-cancelled order items are also set to DECLINED. Sends a decline notification email for person orders.

**Not for cancelling ORDERED or APPROVED orders.** To cancel an active order, use PATCH /api/v1/orders/{orderId} with `{"status": "CANCELLED"}` instead.



# Get order
Source: https://developers.firstbase.com/api-reference/orders/get-order

/openapi.json get /api/v1/orders/{orderId}
Returns full details for a single order belonging to the caller's organization, including order items, current status, and shipping address.



# List orders
Source: https://developers.firstbase.com/api-reference/orders/list-orders

/openapi.json get /api/v1/orders
Returns a paginated list of orders belonging to the caller's organization. Supports filtering by person, date range, status, and sorting. Results are sorted by creation date ascending by default.



# Modify or cancel an existing order
Source: https://developers.firstbase.com/api-reference/orders/modify-or-cancel-an-existing-order

/openapi.json patch /api/v1/orders/{orderId}
Partially update an existing order. Allowed before fulfilment. All request body fields are optional — omit any field to leave it unchanged.

**Cancel an order:** send only `{"status": "CANCELLED"}`. Works for orders in ORDERED, AWAITING_APPROVAL, or DECLINED status (not SHIPPED). This is the correct way to cancel an equipment order; there is no DELETE endpoint for `/api/v1/orders`.

Other modifiable fields: products, shippingAddress, deliverToPersonId, deliverToOfficeId. Address validation workflow is unchanged by this endpoint (same as logistics modify-order: `addressValidationNeeded` is not set via PATCH). Each `products[]` line uses the same `preferredCondition` rules as create order (`skus[]`): NEW, USED, or omitted (defaults to NEW-only preference server-side). When `products` is sent, omitted existing line ids are left unchanged; cancel a line with `cancelled: true` and its `id`. New lines omit `id`. The response `orderItems` list includes cancelled rows—filter by `status` for active lines only.



# Create package
Source: https://developers.firstbase.com/api-reference/packages/create-package

/openapi.json post /api/v1/packages
Creates a new equipment package (onboarding bundle) for the caller's organization. The package defines which SKUs are automatically ordered when a new joiner is onboarded. Gated by a feature flag; returns 403 when the flag is disabled.



# Get package
Source: https://developers.firstbase.com/api-reference/packages/get-package

/openapi.json get /api/v1/packages/{slug}
Returns full details for a single equipment package identified by its URL-safe slug. Includes the package's SKUs, rules, notes, and configuration fields.



# List packages
Source: https://developers.firstbase.com/api-reference/packages/list-packages

/openapi.json get /api/v1/packages
Returns a paginated list of equipment packages (onboarding bundles) belonging to the caller's organization. Each package contains SKUs and rules that determine what equipment new joiners receive automatically.



# Modify package
Source: https://developers.firstbase.com/api-reference/packages/modify-package

/openapi.json patch /api/v1/packages/{slug}
Partially update a package by slug. Modifiable scalar fields: `name`, `active`, `approvalRequired`, `automaticOrder`, `defaultOfficeId`, `deliverySetting`. When `skus` is present, each entry adds or removes a SKU by catalog `id` (set `delete: true` to unlink). Omitted existing SKUs are unchanged; omit `skus` to leave assignments unchanged. `rules` and `usedEquipmentPreferences` replace when present (REQ-025). Setting `active=false` soft-deletes the package. The response includes the full package view plus its `notes` collection. Business-rule rejections (illegal automatic order, duplicate name, archive blocked, etc.) return HTTP 409 with `source="package"` envelope.



# Modify package note
Source: https://developers.firstbase.com/api-reference/packages/modify-package-note

/openapi.json patch /api/v1/packages/{slug}/notes/{noteId}
Partially update a single note attached to a package. Modifiable fields: `note`, `active`. Setting `active=false` soft-deletes the note. The response includes the full package view plus its `notes` collection (upsert semantics surfaced via the refreshed `notes` array).



# Bulk operations
Source: https://developers.firstbase.com/api-reference/people/bulk-operations

/openapi.json post /scim/v2/Bulk
Performs bulk operations using the SCIM protocol as defined by RFC 7644.



# Bulk upsert users
Source: https://developers.firstbase.com/api-reference/people/bulk-upsert-users

/openapi.json post /scim/v2/Users/csv
Parses the CSV file and forwards it as a SCIM Bulk request to create and/or update users.

Expected CSV columns (header row): id, forename, surname, email, secondary_email, package_slug, address_line_1, addressLine2, state/region, city_code, country_code, postal_code, phone_number, send_activation_email, cpf_number.

Notes: 
- id: optional UUID. If present, an update (PUT) is generated; if absent, a create (POST) with a bulkId is generated.
- package_slug: optional; when present and resolvable it is mapped to a packageId.
- send_activation_email: true/false/yes/no/null (case-insensitive).
- File must be uploaded as multipart form-data with field name 'file'.- CPF number is mandatory for Brazilian users.



# Create person
Source: https://developers.firstbase.com/api-reference/people/create-person

/openapi.json post /scim/v2/Users
Creates a new person record in Firstbase using the SCIM 2.0 protocol. Triggers automatic equipment ordering if the person is assigned to an active package. The `userName` field must be a unique email address. Returns 409 if a user with the same `userName` already exists.



# Delete user
Source: https://developers.firstbase.com/api-reference/people/delete-user

/openapi.json delete /scim/v2/Users/{id}
Deleting a User will start the Offboarding process for the user. This is a SOFT delete, in which the user will still have access to the Firstbase platform until offboarding has completed



# Get person
Source: https://developers.firstbase.com/api-reference/people/get-person

/openapi.json get /scim/v2/Users/{id}
Retrieves a person's SCIM representation by their internal Firstbase ID. Use the `attributes` or `excludedAttributes` query parameters to control which SCIM fields are included in the response.



# List people
Source: https://developers.firstbase.com/api-reference/people/list-people

/openapi.json get /scim/v2/Users
Returns a paginated SCIM ListResponse of people in the caller's organization. Filter by email address or name using SCIM filter expressions. Maximum of 50 users per page.



# Offboard person
Source: https://developers.firstbase.com/api-reference/people/offboard-person

/openapi.json post /api/v1/people/{personId}/offboard
Starts offboarding for the person. May create return workflows depending on request body options (for example address confirmation and items not to return).



# Reactivate person
Source: https://developers.firstbase.com/api-reference/people/reactivate-person

/openapi.json post /api/v1/people/{personId}/reactivate
Reactivates a previously offboarded person in the caller's organization. Restores the person for ordering and inventory assignment according to current organization settings.



# Replace person
Source: https://developers.firstbase.com/api-reference/people/replace-person

/openapi.json put /scim/v2/Users/{id}
Performs a full replacement (PUT) of a person's SCIM attributes. All writable fields in the request body overwrite the existing values. Used by identity providers (IdPs) to keep person data in sync. Returns 409 if the updated `userName` conflicts with another existing user.



# Send email
Source: https://developers.firstbase.com/api-reference/people/send-email

/openapi.json post /api/v1/people/{personId}/emails
Triggers an admin email action for the specified person. The `emailType` determines the action:

- **RESEND_ACTIVATION** — Resends the activation email to a person with INVITED status who has a platform account.
- **RESEND_OFFBOARDING** — Resends the arrange-return / offboarding email to a person who is currently being offboarded (OFFBOARDING status).
- **SEND_PLATFORM_INVITE** — Sends a platform access invite email to an ACTIVE person who does not yet have platform access. Creates a platform account and sets the person's status to INVITED.



# Get region
Source: https://developers.firstbase.com/api-reference/regions/get-region

/openapi.json get /api/v1/regions/{id}
Returns full details for a single region accessible to the caller's organization.



# List regions
Source: https://developers.firstbase.com/api-reference/regions/list-regions

/openapi.json get /api/v1/regions
Returns a paginated list of geographic regions associated with the caller's organization. Regions define where inventory levels apply and where warehouses operate. Optionally filter by region name (partial match) or region code. Page and size are 1-based and capped at 100 per page.



# Cancel replacement
Source: https://developers.firstbase.com/api-reference/replacements/cancel-replacement

/openapi.json delete /api/v1/replacements/{replacementId}
Cancels a replacement. Allowed only when status is SUBMITTED. Cascades to cancel the associated return order and releases any reserved inventory. Gated by the FBS_2976_PUBLIC_API_ENTITY_MODIFICATION feature flag.



# Create replacement
Source: https://developers.firstbase.com/api-reference/replacements/create-replacement

/openapi.json post /api/v1/replacements
Creates a replacement consisting of a return order and a new equipment order



# Get replacement
Source: https://developers.firstbase.com/api-reference/replacements/get-replacement

/openapi.json get /api/v1/replacements/{id}
Returns the details of a single replacement order by its unique identifier.



# List replacements
Source: https://developers.firstbase.com/api-reference/replacements/list-replacements

/openapi.json get /api/v1/replacements
Returns a paginated list of replacement orders for the organization. A replacement is created when a defective or lost device needs to be swapped for a new one.



# Cancel return
Source: https://developers.firstbase.com/api-reference/returns/cancel-return

/openapi.json delete /api/v1/return-orders/{returnOrderId}
Cancels a return order. Allowed only when status is SUBMITTED or CONFIRMED. Releases inventory back to active state. Honors offboarding-vs-one-off branching.



# Create return
Source: https://developers.firstbase.com/api-reference/returns/create-return

/openapi.json post /api/v1/returns
Creates a new return order for a person. Items can be identified by inventoryId or serialNumber. If officeId is provided, items are returned to the office (returnMethod forced to SHIPMENT). Otherwise items are returned to the Firstbase warehouse.



# Get return
Source: https://developers.firstbase.com/api-reference/returns/get-return

/openapi.json get /api/v1/returns/{id}
Returns full details for a single return order belonging to the caller's organization. Optionally includes shipment tracking information when includeShipment=true.



# List returns
Source: https://developers.firstbase.com/api-reference/returns/list-returns

/openapi.json get /api/v1/returns
Returns a paginated list of return orders. Each return includes 4 retrieval method types (PL, RETURN_KIT, INBOUND, NOT_MAPPED) with items grouped by method. Empty arrays indicate no items use that method.



# Process return items
Source: https://developers.firstbase.com/api-reference/returns/process-return-items

/openapi.json patch /api/v1/return-orders/{returnOrderId}/items
Bulk-update items on a return order (used when items physically arrive). Each item: `id`, `status`. When `status` is NOT_RETURNED, send `notReturnedDisposition` DEPLOYED (keep deployed; omit deploy fields) or ARCHIVE (`deployReason` required; non-blank `deployReasonDetails` when deployReason is OTHER). Matches org-app Process Return. Offboarding returns: domain validation may still require deployReason for NOT_RETURNED. Additional RETURNED validation may return 400 with domain detail.



# Cancel shipment notice
Source: https://developers.firstbase.com/api-reference/shipment-notices/cancel-shipment-notice

/openapi.json delete /api/v1/shipment-notices/{shipmentNoticeId}
Cancels a shipment notice. Allowed only when notice status is SUBMITTED. Cascades all package item statuses to CANCELLED.



# Create shipment notice
Source: https://developers.firstbase.com/api-reference/shipment-notices/create-shipment-notice

/openapi.json post /api/v1/shipment-notices
Creates a new shipment notice order. Identify the source as SUPPLIER (with purchase_order_number) or OFFICE. Each shipment contains items identified by sku_id with a quantity.



# Get shipment notice
Source: https://developers.firstbase.com/api-reference/shipment-notices/get-shipment-notice

/openapi.json get /api/v1/shipment-notices/{id}
Returns full details for a single shipment notice order belonging to the caller's organization. Each package item includes a full `inventories` list with individual serial numbers and inventory IDs.



# List shipment notices
Source: https://developers.firstbase.com/api-reference/shipment-notices/list-shipment-notices

/openapi.json get /api/v1/shipment-notices
Returns a paginated list of shipment notice orders. V1 exposes a full `inventories` list per package item, replacing the single serial-number field in the legacy endpoint. Supports filtering by status, warehouse, and date range.



# Modify shipment notice
Source: https://developers.firstbase.com/api-reference/shipment-notices/modify-shipment-notice

/openapi.json patch /api/v1/shipment-notices/{shipmentNoticeId}
Partially updates a shipment notice and its packages/items. Editability follows the rule: shipment notice editable when SUBMITTED or PROCESSING with at least one PENDING package. Use `{id, delete: true}` on shipmentNoticePackages or items to remove them. Omit elements to preserve them. Add new packages or items by omitting `id`.



# Get shipment
Source: https://developers.firstbase.com/api-reference/shipment/get-shipment

/openapi.json get /api/v1/shipments
Returns shipment details for the provided tracking numbers, paginated. At least one tracking number must be supplied. Each result includes carrier, tracking status, and the order items associated with the shipment.



# List carriers
Source: https://developers.firstbase.com/api-reference/shipment/list-carriers

/openapi.json get /api/v1/carriers
Returns supported carriers for shipment tracking. You can optionally filter carriers by tracking platform.



# Get warehouse
Source: https://developers.firstbase.com/api-reference/warehouses/get-warehouse

/openapi.json get /api/v1/warehouses/{id}
Returns full details for a single warehouse accessible to the caller's organization.



# List warehouses
Source: https://developers.firstbase.com/api-reference/warehouses/list-warehouses

/openapi.json get /api/v1/warehouses
Returns a paginated list of Firstbase warehouses that the caller's organization can use when creating inventory orders or shipment notices. Optionally filter by country code (ISO 3166-1 alpha-2). Page and size are 1-based and capped at 100 per page.



# Rate limits
Source: https://developers.firstbase.com/rate-limits

Per-key quotas, response headers, 429 body, and recommended client backoff.

The Public API limits each API key independently. One key is one bucket. Limits apply to `/api/*` and `/scim/v2/*`.

| Window | Limit |
| - | - |
| Sustained | 600 requests / 60 seconds |
| Burst | 150 requests / 10 seconds |
| Concurrency | 10 in-flight requests per key per pod |

## Response headers

Every authenticated response includes both header families, including 429s.

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Max requests in the tighter of the sustained and burst windows |
| `X-RateLimit-Remaining` | Requests left in that same window |
| `X-RateLimit-Reset` | Unix epoch seconds when that window resets |
| `RateLimit-Limit` | Same as `X-RateLimit-Limit` |
| `RateLimit-Remaining` | Same as `X-RateLimit-Remaining` |
| `RateLimit-Reset` | Seconds until that window resets (delta, not epoch) |

`X-RateLimit-Reset` is epoch seconds. `RateLimit-Reset` is a delta in seconds. Do not treat them as interchangeable. A burst 429 shows remaining `0` and `RateLimit-Reset` equal to the burst TTL, matching `Retry-After`.

## When you are limited

A rejected request returns **429** with `Retry-After` (seconds) and:

```json theme={null}
{"errors":[{"detail":"...","source":"publicapi"}]}
```

## Recommended backoff

1. Honour `Retry-After`. Wait that many seconds before retrying.
2. When `RateLimit-Remaining` is `0`, wait `RateLimit-Reset` seconds before sending more traffic.
3. Cap retries. Treat a sequence of 429s as a signal to slow the whole client, not just the one request.

<Warning>
  Clients that ignore `Retry-After` will keep receiving 429s until the window rolls over.
</Warning>