Idempotency

getpaid API implements an idempotency mechanism to ensure that repeating the same request multiple times produces the same result as executing it once, so the final state or outcome remains consistent. It is specially useful in scenarios where network issues, timeouts, or uncertainties about the status of previous requests can lead to potential problems. It is recommended to implement the idempotency mechanism in your system to prevent unintended duplicates.

The idempotency key is an unique identifier, per endpoint and integrator account, that clients include in the Getpaid-Idempotency-Key header of the HTTP request. This key helps the server identify whether the request has been previously processed. It is recommended the use of a version 4 UUID as the idempotency key. The uniqueness of the key is a responsibility of the client.

Idempotency is intended for endpoints that are not idempotent by nature and the response is not the same if the call is executed several times, such as creating a new invoice or deleting an account link. In the getpaid API, the idempotency mechanism is supported in almost all POST and DELETE endpoints. The usage of the idempotency mechanism is explicitly defined by the support of the Getpaid-Idempotency-Key header in the endpoint documentation.

The idempotency key has a defined lifecycle of 7 days within the system. After this period, you may reuse the key. It only must to be unique per endpoint and integrator account.

Only successful responses are cached. In case of an error, either a client-side (4XX HTTP status code) or a server-side (5XX HTTP status code), the response is not cached and the client can retry with the same idempotency key until the request is successful.

How it works

The idempotency mechanism implemented behaves in the following way depending on the different scenarios:

• Not used: the idempotency key was not used (or it was used at least 7 days before) for the same endpoint and integrator account. In this case, the server processes the request and returns the result saving the response, if applicable, in the system for subsequent requests.
• Already used: the idempotency key was used for the same endpoint and integrator account. In this case, the server retrieves the response saved in the system and returns it to the client. This way, the client can know the result of the previous request without duplicating the operation. The response is the same as the one returned in the first request but returning also the HTTP response headers Cache-Control: max-age=N, Age and Expires to explicitly indicate that it is a cached response and the time it was cached and it will expire.
• Pending: the idempotency key was used for the same endpoint and integrator account, but the request is still being processed. In this case, the server returns a 409 Conflict status code to indicate that the request is still in progress and it was blocked to avoid duplications. In case the first request is not being processed for more than 5 minutes, the idempotency key is released and the next request will be processed as a new one.
• Idempotency mechanism unavailable: the idempotency system is unavailable. In this case, the server returns a 500 Internal Server Error status code to indicate that the request cannot be processed due to the unavailability of the system. The request can be retried later or without the idempotency key under the client's responsibility.