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. |
| 400 | invalid_body | A POST body that isn't JSON, or isn't the shape the endpoint takes. |
| 403 | plan_required | The workspace's plan doesn't include the API. |
| 403 | insufficient_scope | The key is read-only. Make one that can record payments. |
| 404 | not_found | No such endpoint, or no record with that id in this workspace. |
| 405 | method_not_allowed | Everything is GET, except POST /v1/payments. |
| 409 | conflict | The write breaks a rule, like paying more than the balance or paying a void invoice. message says which. |
| 409 | idempotency_conflict | That Idempotency-Key was already used with a different body. |
| 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.
Retrying writes safely
Send an Idempotency-Keyheader (any unique string, like your accounting system's payment id) with every POST. If the connection drops and you send the same request again with the same key, Harlo answers with the first result instead of recording the payment twice, and adds Idempotent-Replayed: true. Keys are remembered for 24 hours.
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.