Responses

All API calls will return a standard HTTP response code as indicated below. Response payload examples are indicated below, however each API endpoint should indicate the actual structure of the response payload.

Success

HTTP Code: 200

Example Response

    {
        "status": "success",
        "request_id": "<request id>"
    }

Success No Content

HTTP Code: 204

Note

No response payload will be provided

Paginated Lists

API endpoints that return lists of resources use a paginated response envelope. The response includes the total count and URLs for navigating between pages.

Example Response

{
    "count": 356,
    "next": "https://<domain>/api/v1.5/products/?page=2",
    "previous": null,
    "results": [
        { "..." : "..." }
    ]
}

Field	Type	Description
`count`	integer	Total number of results across all pages
`next`	string or null	URL for the next page of results, or `null` if on the last page
`previous`	string or null	URL for the previous page of results, or `null` if on the first page
`results`	array	The list of resource objects for the current page

To retrieve a specific page, add the page query parameter to the endpoint URL:

GET /api/v1.5/products/?page=3

Note

Paginated responses are used by LucidSource list endpoints (products, batches, assets). LucidRetail endpoints return individual resources.

Bad Request

HTTP Code: 400

Returned when the request payload is malformed or contains invalid data. The reason field contains one or more field-level validation errors.

Example Response

{
    "status": "invalid payload",
    "reason": {
        "items": [
            "Unknown LucidID(s)."
        ]
    }
}

Unauthorized

HTTP Code: 401

Note

No response payload will be provided

Forbidden

HTTP Code: 403

Returned when the authenticated user does not have permission to perform the requested action. This can occur when accessing resources belonging to a different Brand or Company than the one associated with your API credentials.

Note

Some legacy endpoints return 403 with an "invalid payload" status for validation errors. This is non-standard — new endpoints use 400 for validation errors and reserve 403 for authorization failures.

Method Not Allowed

HTTP Code: 405

Example Response

{
    "detail": "Method \"PUT\" not allowed."
}

Application Error

HTTP Codes: 500, 502, 503, 504

Note

No response payload will be provided

Error Handling

Retry Strategy

Not all errors should be retried. Use this guide to determine the appropriate action:

HTTP Code	Meaning	Retry?	Action
`400`	Bad Request	No	Fix the request payload and resubmit
`401`	Unauthorized	Once	Refresh your access token, then retry the request
`403`	Forbidden	No	Check your API credentials and permissions
`404`	Not Found	No	Verify the resource UUID or endpoint URL
`405`	Method Not Allowed	No	Use the correct HTTP method
`429`	Too Many Requests	Yes	Wait for the duration in the `Retry-After` header
`500`-`504`	Server Error	Yes	Retry with exponential backoff

Exponential Backoff

For 429 and 5xx errors, use exponential backoff:

Wait 1 second, then retry
If still failing, wait 2 seconds, then retry
Double the wait time on each subsequent failure (4s, 8s, 16s…)
Cap the maximum wait at 60 seconds
Give up after 5 retries

Common Error Patterns

Invalid LucidIDs — Submitting a LucidID that doesn’t exist or belongs to a different dispensary returns a 400 with details in the response body. Always validate LucidID format (20-character base57 string) before making API calls.

Expired tokens — A 401 response typically means your access token has expired. Request a new token and retry. See Token Expiration for details.

Rate limiting — A 429 response means you’ve exceeded the rate limit. See the product-specific rate limits pages for details: LucidSource, LucidRetail.