Overview

If an API request is successful, the API returns an HTTP status code appropriate for that request (e.g. 200 OK, 201 Created, 204 No Content).

If the server cannot process your request, the API typically returns a 4xx HTTP status code. For example:

• 403 Forbidden: You do not have access to this resource
• 404 Not Found: This resource does not exist, it may have been deleted or it may have never existed at all.
• 429 Too Many Requests: This request was rate limited, see the Rate Limiting section for more info.
• 400 Bad Request: We could not process this request. Typically this means the endpoint does not support the request you made, perhaps the parameters supplied with the request were incorrect, or something else about the request was malformed. The response should be valid JSON, with an "errorMessage" key which explains why the request could not be processed.

🚧

Expired accounts and Authentication

Note that when an account expires, it enters a grace period, however the API key remains valid. Some endpoints may still be active so that there is no data loss (e.g. new lead POST to /v1/events) however the account may be in a locked down state and will receive a 403 Forbidden response for most other requests.

If the server is unable to process a request because it is overloaded, or because we made a programming error, you may see a 5xx HTTP status code (e.g. 500 Internal Server Error, 503 Service Unavailable, 504 Gateway Timeout, etc.).

Retrying failed requests

Systems should make sure to implement throttling logic when receiving a 5xx HTTP Status code.

A common technique is to use Truncated exponential backoff.

Example:

1. Make a request to Follow Up Boss API.
2. If the request fails, wait 1 + random_number_milliseconds seconds and retry the request.
3. If the request fails, wait 2 + random_number_milliseconds seconds and retry the request.
4. If the request fails, wait 4 + random_number_milliseconds seconds and retry the request.

And so on, up to a maximum_backoff time.

Continue waiting and retrying up to some maximum number of retries, but do not increase the wait period between retries.

Where:

• The wait time is min(((2^n)+random_number_milliseconds), maximum_backoff), with n incremented by 1 for each iteration (request).
• random_number_milliseconds is a random number of milliseconds less than or equal to 1000. This helps to avoid cases where many clients get synchronized by some situation and all retry at once, sending requests in synchronized waves. The value of random_number_milliseconds is recalculated after each retry request.
• maximum_backoff is typically 32 or 64 seconds. The appropriate value depends on the use case.

It's okay to continue retrying once you reach the maximum_backoff time. Retries after this point do not need to continue increasing backoff time. For example, if a client uses an maximum_backoff time of 64 seconds, then after reaching this value, the client can retry every 64 seconds. At some point, clients should be prevented from retrying infinitely.

How long clients should wait between retries and how many times they should retry depends on your use case and network conditions.