Errors and rate limits
Status codes you can branch on, and a message you can show a person.
The error shape
Every error has the same body. Branch on code; it won't change. Show message; it may be reworded.
{
"error": {
"code": "invalid_parameter",
"message": "limit must be a whole number from 1 to 100.",
"param": "limit",
"request_id": "fc3abb74-0f0f-4eb8-91c0-a1c30cb84385"
}
}Codes
| Status | code | What to do |
|---|---|---|
| 400 | invalid_parameter | A query parameter is wrong. param names it; message says what it takes. |
| 401 | invalid_api_key | No key, or not one Harlo issued. Check it was copied whole, starting hk_. |
| 401 | api_key_revoked | An admin revoked the key. Make a new one. |
| 401 | api_key_expired | The key passed its expiry date. Make a new one. |
| 403 | plan_required | The workspace's plan doesn't include the API. |
| 404 | not_found | No such endpoint, or no record with that id in this workspace. |
| 405 | method_not_allowed | Only GET is supported in this version. |
| 429 | rate_limited | More than 120 requests in a minute from this key. Wait for Retry-After. |
| 500 | server_error | Something broke on Harlo's side. Retry; if it persists, send us the request_id. |
Rate limits
Each key can make 120 requests a minute. Every response says where you stand:
X-RateLimit-Limit | Requests allowed per minute (120). |
X-RateLimit-Remaining | How many are left this minute. |
X-RateLimit-Reset | When the minute resets, in Unix seconds. |
Retry-After | On a 429 only: seconds to wait before trying again. |
A full sync with limit=100 reads 12,000 records a minute, which is plenty for most workspaces. If you need more, email support@goharlo.com.
Request ids
Every response carries an X-Request-Id header, and errors repeat it in the body. Include it when you contact support and we can find the exact request.
Versions
The API is versioned in the path (/v1). Within v1 we only add things: new fields, new endpoints, new filters. Write your code to ignore fields it doesn't know. Anything that would break existing code goes in a new version, announced in the changelog well ahead. The Harlo-Versionheader shows the date of the description you're talking to.