Status codes

Introduction

Skovik uses conventional HTTP response codes to indicate success or failure of an API request.
In general, codes in the 2xx range indicate success,
codes in the 4xx range indicate an error on your side (e.g. a required parameter was missing, uniqueness validation failed, etc.)
and codes in the 5xx range indicate an error with Skovik's system.

// The error response have the following structure. An array
// of error objects may be returned, but typically it's a single
// error.
//
// A "code" key may be included, with an error code. Printing or
// logging the error object is a good idea and will aid
// debugging and other inquires.

{
  "errors": [
    {
      "id": "a62f8b4af8821bea623f835320aaa6ba",
      "status": "400",
      "code": "email_exist",
      "title": "Bad request",
      "detail": "Invalid email"
    }
  ]
}

Examples of HTTP status codes

200 - OK
Everything worked as expected.

201 - Created
Resource has been created

202 - Accepted
Indicate that processing will occur async,
in a little while.

204 - No Content
This code indicates that a request has succeeded.

400 - Bad Request
Often missing a required parameter.

401 - Unauthorized
No valid API key provided.

404 - Not Found
The requested resource does not exist.

422 - Unprocessable
Parameters were valid but request failed,
usually due to a validation error.

423 - Locked
A soft limit has been reached. Get in touch with us to have it raised.

429 - Too Many Requests
Rate limiting has kicked in.

500 - Server Error
Something went wrong on our end.

503 - Service Unavailable
Overloaded or temporarily down (could be maintenance).

Handling Errors

The API can return errors for many reasons, such as invalid parameters, authentication errors, and network unavailability.
Handle errors gracefully where possible. Usually by scheduling a retry with exponential backoff.

For example, expect to receive the occasional 503 Service Unavailable response when we're doing system upgrades.

Make sure retries resolve the API hostname anew.
We use short DNS TTL values to provide high availability and fail-over in case of network issues.
TTL-values must be respected to reap the benefits of our high-availability infrastructure.

👍

Exponential Backoff

Exponential backoff is a common error handling strategy for network applications,
whereby the client periodically retries a failed request with an increasing delay between each attempt.
For errors at the network layer (connection errors) as well as server errors (5xx) exponential backoff is a good strategy.
Conversely, it is not useful for authorization errors or resource not found (4xx).
Keep in mind that connection issues may occur both at the server side (Skovik's systems are unreachable) as well as on the client (e.g. your ISP is down).

A good formula is Delay(n) = (10 ^ n) retried up to 5 times, where n is the number of attempts and the delay is measured in seconds.
This formula will make a few attempts in quick succession and concede defeat after ~24 hours.
Exponential backoff create resilience, where most transient issues resolve themselves automatically and without any intervention.

Note that sequential requests may be inadvertently reordered by your backoff mechanism.
If serializability is required this must be taken into account.