Skip to main content

​
Errors

Every error comes back as JSON with a message in plain words. Some errors also carry a machine-readable error code, and validation errors can name the field in parameter:
We’re moving every error to one shape, { "error": "<code>", "message": "…" }, with the usual statuses: 401 for a bad key, 403 for a missing permission, 402 for a missing subscription. This page will be updated the day that ships. Until then, act on the HTTP status, use error when it’s there, and don’t parse message.

​
Status codes

​
Rough edges

A few errors don’t look the way they should yet. Until the next API update:
  • Adding a participant without program answers 500.
  • An invalid email address, or a first and last name longer than 24 characters together, answers 400 with a message that doesn’t say which. Check both before you send them.
  • On some older plans, running out of invitations answers 500 with a message that starts “Not enough remaining invitations”.
  • A 500 can carry internal error text. Log it, but don’t show it to your users.
  • The per-address rate limit answers in plain text, not JSON (see Rate limits).

​
Retrying safely

  • Retry 429, 503 and 5xx responses with exponential backoff (for example 1, 2, 4, 8 seconds, up to a minute), and wait at least Retry-After when it’s there. Don’t retry other 4xx responses unchanged.
  • When you add participants, always send an Idempotency-Key. Generate a UUID for each add and reuse it on every retry of that add. Hoppier then adds the person once, however many times the request arrives. How the key works.
  • Adding someone who’s already in the program normally returns their existing record instead of adding them twice, but only an Idempotency-Key guarantees that a retry is safe.

​
Rate limits

Two limits apply to every request: Reads are the GET requests and writes are the POST requests. All the keys in a company share the account limit, and Hoppier’s Zapier app counts towards it too. If Hoppier can’t check the account limit, reads go through and writes answer 503 with error: rate_limit_unavailable and Retry-After: 5. Nothing was written, so retry.