API Reference

Error handling

Suggest Edits

HTTP Errors

Errors will fall into one of three main categories:

  • Content Errors - missing or invalid content in the request.
  • Network Errors - connection issue or timeout between the client and Signifyd's servers.
  • Server Errors - problems with Signifyd servers.

Content Errors

When a content-related 4xx error is received, depending on the error code, you may need to correct the API request and payload before retrying the request. 4xx errors can be broken into two groups, fatal and transient.

Fatal errors are due to invalid/bad data or lack of proper permissions. These errors require the root cause to be addressed before the request can be retried.

Examples of fatal 4xx errors that require correction before being retried:

  • 400 Bad Request - The request could not be parsed, generally due to bad syntax.
  • 401 Unauthorized - The request could not be authenticated due to missing or invalid credentials.
  • 403 Forbidden - You do not have permission to access the resource.

Transient errors have a variety of root causes that may or may not require the request to be corrected. For this reason, transient errors can be retried initially without correction. Further failures may indicate the request needs to be corrected.

Examples of transient 4xx errors that may be retried initially without correction:

  • 404 Not Found - The resource doesn't exist.
  • 408 Request Timeout - The client never finished sending the full request.
  • 409 Conflict - Conflict with state of the resource on server. Can occur with too many PUT requests in rapid succession.
  • 429 Too Many Requests - The request was not accepted because the application has exceeded the rate limit.

🚧

Important

On continued failure due to transient 4xx errors, still review the request, as depending on the root cause these may also require correction of the request itself.

Network Errors

Signifyd currently enforces a timeout that results in 504 errors when an API request takes longer than 60 seconds to complete. At the moment, there is no way to differentiate between 504 errors caused by networks versus server issues.

Server Errors

Server errors (all other 5xx errors) result from a problem with Signifyd’s servers. These errors are the most difficult to troubleshoot and we work to make them as rare as possible, but integrations should handle them using the retry strategies below when they do arise.

Retry Strategies

For retryable errors (ie 5xx errors and transient 4xx errors), follow the retry guidance below. The retry approach and coverage will differ based on whether your integration with Signifyd is at pre-authorization via our Checkout API or post-authorization via our Sale API.

Decisioning

The following guidance pertains only to Signifyd endpoints that return a new or updated decision.

Pre-Authorization APIs

EndpointsCheckout
Retry GuidanceIf your request takes more than 1500ms to return a response or returns a 5xx response, we recommend 2 immediate retries, spaced 1500ms apart.

Move forward to authorization if not successful after 2 retries. If authorization is successful, send Signifyd an asynchronous Sale call (see below) to ensure coverage for the order.
RemediationUpon further timeouts, follow the remediation steps in the Post-Authorization APIs section below.

Post-Authorization APIs

EndpointsSale, Reroute
Retry GuidanceIf your request takes more than 1500ms to return a response or returns a 5xx response, we recommend retying after a 2 second wait and continuing consecutive retries over the course of an hour using exponential backoff / jitter as described here.
ResolutionDo not proceed to order fulfillment until Signifyd has provided a decision (i.e. the API request has been successful).

Check our support status page for an API outage. If you do not get a 2xx after 1 hour, reach out to Signifyd support.

Non-Decisioning

The following guidance pertains to Signifyd endpoints that do not return a new or updated decision.

APIs

EndpointsAll other (excluding Checkout, Sale, Reroute)
Retry GuidanceIf your request takes more than 60s to return a response or returns a 5xx response, we recommend retying after a 2 second wait and continuing consecutive retries over the course of an hour using exponential backoff / jitter as described here.
ResolutionCheck our support status page for an API outage. If you do not get a 2xx after 1 hour, reach out to Signifyd support.

Webhooks

EndpointsAll webhooks
Retry GuidanceIf you are unable to review your order queue (e.g. submit successful thumbs up or thumbs down on the agent console triggers a webhook request) or receive Signifyd’s decisions via webhooks or during outages, we recommend making a Get Decision request for the order in question.

Webhooks may still arrive delayed and/or out of order. You can compare timestamps in the webhook body, but not that the included timestamp represents the time the decision was made by our system, not when the original request was made.

For confirmation, it is best to make a fresh Get Decision request, as this will always return the most recent decision.
ResolutionDo not proceed to order fulfillment until Signifyd has provided a decision.

Check our support status page for a webhooks outage. If there are no reported delays, reach out to Signifyd support if you do not receive webhooks 1 hour after the API request or thumbs up/down.

Updated 3 months ago