Error Handling & Error Codes

Learn how to handle and recover from errors received from Qordoba’s API.

Over its lifetime, your Qordoba integration may have to deal with errors that occur when making API requests to Qordoba. There are a few major categories of errors that your API integration could face:

  • Content errors: Errors that occur because the API request’s content was invalid in some way, and which manifest as an HTTP response with a 4xx status code. For example, the API servers may return a 401 if an invalid API key was provided, or a 400 if a required parameter was missing.

  • Network errors: Errors that occur due to intermittent communication problems between client and server, and which manifest as low-level errors like socket or timeout exceptions. For example, a client may time out while trying to read from Qordoba’s servers, or an API response never received as a connection is terminated prematurely. Note that 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.

  • Server errors: Errors that occur because there was a problem on Qordoba’s side, and which manifest as an HTTP response with a 5xx status code. Qordoba endeavors to make these errors as rare as possible, but integrations should be able to handle them gracefully when they do appear.

The right approach and idempotency semantics to use for handling errors depend on the type of error being handled.

Qordoba uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Stripe's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

200 - OK

Everything worked as expected.

400 - Bad Request

The request was unacceptable, often due to missing a required parameter.

401 - Unauthorized

No valid API key provided.

402 - Request Failed

The parameters were valid but the request failed.

404 - Not Found

The requested resource doesn't exist.

409 - Conflict

The request conflicts with another request.

429 - Too Many Requests

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

500, 502, 503, 504 - Server Errors

Something went wrong on Qordoba's end. (These are rare.)

Safely retrying requests with idempotency

An important idea in the design of web APIs is idempotency, defined as being able to apply the same operation multiple times without changing the result beyond the first try. Because a certain amount of intermittent failure is to be expected, clients need a way of reconciling failed requests with a server, and idempotency provides a mechanism for that.

GET requests and DELETE requests are guaranteed to be idempotent by Qordoba’s API, so it’s always safe to retry them. POST requests can be made idempotent through the inclusion of an idempotency key, which will prompt Qordoba’s API to do the bookkeeping required to prevent duplicate operations.

For example, if a request to create a file does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one charge is created.

Content errors

Content errors are the result of the contents of an API request being invalid and manifest as a 4xx status code. Integrations should correct the original request, and try again. Depending on the type of user error (e.g. a card is declined), it may be possible to handle the problem programmatically, and those that can be include a code field to help an integration react appropriately. See error codes for more details.

There are some caveats to the above — for example, a request that’s rate limited with a 429 can produce a different result with the same key because rate limiters run before the API’s layer. The same goes for a 401 that omitted an API key, or most 400s that sent invalid parameters.

Network errors

Network errors are the result of connectivity problems between client and server and tend to manifest as low-level errors like socket or timeout exceptions.

Most client libraries can generate and retry requests automatically, but need to be configured to do so. They perform their first retry quickly after the first failure, and subsequent ones on an exponential backoff schedule, with the premise that a single failure is often a random occurrence, but a pattern of repeated failures is likely representative of a chronic problem.

Server errors

Server errors are the result of a server-side problem and manifest as a 5xx status code. These errors are the most difficult to handle, so we try to ensure that they happen as infrequently as possible.

Like with user errors, the API’s idempotency layer caches the result of POST mutations that result in server errors (specifically 500s, which are internal server errors), so retrying them with the same idempotency key will usually produce the same result. The request can be retried with a new idempotency key, but we’d advise against it because it’s possible for the original one to have produced side effects.

The result of a 500 request should be treated as indeterminate. The most likely time to observe one is during a production incident, and generally during such an incident’s remediation, Stripe engineers will examine failed requests and try to appropriately reconcile the results of any mutations that resulted in 500s.

While the idempotency-cached response to those requests won’t change, we will try to fire webhooks for any new objects created as part of Qordoba's reconciliation. The exact nature of any retroactive changes in the system depend heavily on the type of request. For example, if creating a charge 500s but we detect that the information has gone out a payment network, we’ll try to roll it forward. If not, we’ll try to roll it back. However, ideal results under these circumstances are not guaranteed, and requests resulting in a 500 may produce user-visible side effects.

Error Codes