API keys
All requests require an API key passed via the X-API-Key header:
curl https://api.halal.sh/v1/instruments/AAPL/compliance \
-H "X-API-Key: hsh_live_abc123..."
hsh_live_ (production) or hsh_sandbox_ (sandbox).
Managing keys
Create and revoke API keys from your developer dashboard. You can create multiple keys to separate environments or applications.
Never expose your API key in client-side code, public repositories, or browser requests. Always call the API from your backend.
Rate limits
Rate limits depend on your plan:
| Plan | Requests/day | Requests/minute | Auto-analyses/day |
|---|
| Sandbox (free) | 100 | 10 | 0 |
| Pro ($49/mo) | 2,000 | 120 | 100 |
| Enterprise | Unlimited | Dedicated | Unlimited |
Sandbox keys (hsh_sandbox_) have access to a curated set of 10 popular stocks and 2 ETFs (SPY, HLAL) with real data and identical response schemas. Upgrade to Pro for full universe access.
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1872
X-RateLimit-Reset: 1741478400
429 Too Many Requests:
{
"error": {
"code": "rate_limit_exceeded",
"message": "Daily request limit exceeded. Resets at 2026-03-09T00:00:00Z.",
"retry_after": 3600
}
}
Error handling
All errors follow a consistent format:
{
"error": {
"code": "not_found",
"message": "No instrument found for symbol 'XYZ'."
}
}
Error codes
| HTTP Status | Code | Description |
|---|
| 400 | bad_request | Invalid parameters |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Endpoint not available on your plan |
| 404 | not_found | Instrument or resource not found |
| 429 | rate_limit_exceeded | Too many requests |
| 500 | internal_error | Server error — retry with backoff |
Response envelope
All successful responses use a consistent envelope:
{
"data": { ... },
"meta": {
"request_id": "req_abc123",
"methodology": "aaoifi_standard_21@2026.1",
"as_of": "2026-03-08T12:00:00Z"
}
}
meta.request_id is useful for debugging — include it in support requests.
Versioning and stability
The API is versioned via the URL path (/v1/). Within a version, we guarantee:
- No fields removed or renamed
- No field types changed
- No URL structure changes
We may add new fields to responses, new endpoints, new optional query parameters, and new enum values within the same version. Design your client to handle unknown fields and unknown enum values gracefully — for example, treat an unrecognized ComplianceStatus as pending.
Breaking changes will ship in a new version (/v2/) with a migration guide and deprecation timeline for the previous version.