Edge cases and error handling

Before going live there are a number of scenarios that must be considered in order to provide a complete integration. Some of these are items within your own codebase that Twisto does not revise explicitly and are expected to be completed by the time you request access to production.

Something not working as expected? Contact us at tech@twisto.cz with your technical questions.

Edge cases

Ensure you thoroughly test your integration, including scenarios with:

Incomplete data
Invalid data
Duplicate data (e.g., retry the same request to see what happens)

Timeouts and repeat transactions

There will inevitably be times when no response is received due to connection issues or similar. When this occurs, Twisto expects transactions to be re-attempted until a valid response is received or until a timeout period expires.

Non-Transactional API calls

Some API calls can simply be re-sent without the need to identify that the call is a retry. The /checkouts endpoint for example can be repeatedly called with the same references and payload info with no issue. The timings of these have little impact as each request is new, and independent of the first failed call.

Transactional API calls

Other API calls require retry attempts to be identified to prevent double charges and also to avoid duplicate reference errors for the order reference being passed.

Any Transactional API calls to the /charges or /refunds endpoints for example will need to use the same 'Idempotency-key' in the header as the original request to flag this.

METHOD	TYPE
POST /checkouts	Non-transactional
POST /checkouts/{id}/cancel	Transactional
POST /charges	Transactional
POST /refunds	Transactional

The timings of these retries is recommended as follows:

ATTEMPT NUMBER	DELAY BEFORE ATTEMPT (SECONDS)	TIMEOUT PERIOD (SECONDS)	TOTAL TIME ELAPSED (SECONDS)
1	N/A	20	20
2	10	10	40
3	5	5	50
4	5	5	60

Review your logging

We recommend that you log all important data on your end. Your own logs will be extremely valuable if your server has a problem contacting Twisto or there's an issue with your API keys—both cases would prevent us from logging your request.

Regularly examine your logs to ensure they're storing all the information you may need and they aren't storing anything of a sensitive nature. Check if you identify any recurrent error which may require some adjustment in your integration.

Change and secure your API keys

Make sure you keep your API credentials private.

Error codes

The API uses consistent error responses and follows REST status code conventions where appropriate.

In order to provide more information or a sub-division of status codes an Error object is returned for all non 2xx status codes. The Error object contains a more specific code and error message.

The status codes that may be returned from the API are detailed below:

STATUS CODE	DESCRIPTION
2xx	OK Everything worked correctly.
400	Bad Request There is an error in the request object.
401	Unauthorized No valid API key provided.
402	Request Failed Request could not be processed, see error code for more information.
403	Forbidden Operation is not allowed (customer did not authorise action).
404	Not Found The resource does not exist.
409	Conflict The request is a duplicate of a previous request
429	Too Many Requests Requests are rate limited - you are making too many requests.
5xx	Server Error An error has occurred on Twisto's end.

Specific error codes for each endpoint are detailed on the appropriate endpoint page.

For BadRequest responses you can find the specific error detail in the details section of the Error object.

"error": {
  "code": "string",
  "message": "string",
  "details": [
    {
      "name": "string",
      "message": "string"
    }
  ]
  }