Skip to content
DevelopersGet an API key

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.

JSON
{
  "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

StatuscodeWhat to do
400invalid_parameterA query parameter is wrong. param names it; message says what it takes.
401invalid_api_keyNo key, or not one Harlo issued. Check it was copied whole, starting hk_.
401api_key_revokedAn admin revoked the key. Make a new one.
401api_key_expiredThe key passed its expiry date. Make a new one.
400invalid_bodyA POST body that isn't JSON, or isn't the shape the endpoint takes.
403plan_requiredThe workspace's plan doesn't include the API.
403insufficient_scopeThe key is read-only. Make one that can record payments.
404not_foundNo such endpoint, or no record with that id in this workspace.
405method_not_allowedEverything is GET, except POST /v1/payments.
409conflictThe write breaks a rule, like paying more than the balance or paying a void invoice. message says which.
409idempotency_conflictThat Idempotency-Key was already used with a different body.
429rate_limitedMore than 120 requests in a minute from this key. Wait for Retry-After.
500server_errorSomething 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-LimitRequests allowed per minute (120).
X-RateLimit-RemainingHow many are left this minute.
X-RateLimit-ResetWhen the minute resets, in Unix seconds.
Retry-AfterOn 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.

NextWebhooks