Your Falu integration might have to deal with errors at some point when making requests to the Falu API. These errors fall into three major categories:
- Content error - invalid content in the API request
- Network error - Intermittent communication problems between client and server.
- Server error - A problem with Falu servers.
The right approach and idempotency semantics to use for handling errors depend on the type of error being handled.
The Falu API applied idempotency for
DELETErequests an this guide makes several references to it. See the idempotency documentation if you need to familiarize yourself with the concept and to see how the Falu API applies it.
Content errors are the result of the contents of an API request being invalid and return an HTTP response with a
4xx error code. For example, the API servers might return a
401 if an invalid API key was provided, or a
400 if a required parameter was missing. Integrations should correct the original request, and try again. Depending on the type of the user error (e.g., a transfer being denied), it may be possible to handle the problem programmatically. In these cases, a
title property is included to help an integration react appropriately. See error codes for more details.
POST operation using an idempotency key, as long as an API method began execution, Falu's API servers will cache the results of the request regardless of what they were. A request that returns a
400 sends back the same
400 if followed by a new request with the same idempotency key. Generate a fresh idempotency key whe modifying the original request to get a successful result. This operation does contain some caveats. For example, a request that's rate limited with a
429 can produce a different result with the same idempotency key because rate limiters run before the API's idempotency layer. The same goes for a
401 that omitted an API key, or most
400s that send invalid parameters. Even so, the safest strategy where
4xx errors are concerned is to always generate a new idempotency key.
Network errors are the result of connectivity problems between client and server and return low-level errors lke socket or timeout exceptions. For example, a client might timeout while trying to read from Falu's servers or an API response might never be received because a connection terminates prematurely. A network error wouldn't necessarily have otherwise been a successful request - it can also be another type of error that's been cloaked by an intermittent problem.
This class of errors is where the value of idempotency keys and request retries is most obvious. When intermittent problems occur, clients are usually left in a state where they don't knw whether or not the server received the request. To get a definitive answer, they should retry such requests with the same idempotency keys and the same parameters until they're able to receive a result from the server. Sending the same idempotency key with different parameters produced an error indicating that the new request didn't match the original.
Most official client libraries can generate idempotency keys and retry requests automatically, but need to be configured to do so. They perform their first retry quickly after the first failure, and subsequent retries on an exponential backoff schedule, the assumption being that a single failure is often a random occurrence, but a pattern of repeated failures likely represents a chronic problem.
Server errors are the result of a problem with Falu's server and return an HTTP response with a
5xx status code. These errors are the most difficult to handle and we work to make them as rare as possible - but integrations should be able to handle them when they do arise.
As with user errors, the idempotency layer caches the result of
POST mutations that result in server errors (specifically
500s, which as internal server errors), so retrying them with the same idempotency key usually produces the same result. The client can retry the request with a new idempotency key, but we advise against it because the original key may have produced side effects.
You should treat the result of a
500 request as indeterminate. The most likely time to observer one is during a production incident, and generally during such an incident's remediation. Falu engineers examine failed requests and try to appropriately reconcile the results of any mutations that result in
500s. While the cached response to those requests won't change, we'll try to fire webhooks for any new objects created as part of Falu's reconciliation. The exact nature of any retroactive changes in the system depends heavily on the type of request. For example, if creating a transfer returns a
500 error but we detect that the information has gone out to a payment provider/network, we'll try to roll it forward. If not, we'll try to roll it back. If this doesn't resolve the issue, you may still see requests with a
500 error that produce user-visible side effects.
Treat requests that return
500errors as indeterminate. Although Falu tries to reconcile their partial state in the most appropriate manner and also fire webhooks for new objects that are created, ideal results are not guaranteed.
Integrations that want to maximize robustness must configure webhook handlers that are capable of receiving event objects that have never been seen in an API response. One technique for cross-referencing these new objects with the data from an integration's local state is to send in a local identifier with the metadata when creating new resources with the API. That identifier appears in the metadata property of an object going out through a webhook, even if the webhook is generated later as part of reconciliation.
The X-Should-Retry header
A client library can't always determine with certainty if it should retry based solely on a status code or content in the response body. The API response with the
X-Should-Retry header when it has additional information that the request is retryable:
trueindicates that a client should retry the request. Clients should still wait some amount of time (probably determined according to an exponential backoff schedule) before making the next request so as not to overload the API.
falsemeans that a client should not retry the request because it won't have an additional effect.
X-Should-Retrynot set in the response indicates that the API can't determine whether or not it can retry the request. Clients should call back to other properties of the response (like the status code) to make a decision.
The retry mechanisms built into Falu's client libraries respect
X-Should-Retry header automatically. If you're using one of them, you don't need to handle it manually.