All Akahu API responses (and requests!) are JSON formatted, and should include a Content-Type: application/json header.

We endeavour to keep a consistent style in our API responses.

{
  "success": true,
  "item_id": "user_ck9uh3kex000107muemzpdkr7"
}

{
  "success": true,
  "item": {
    "_id": "user_ck9uh3kex000107muemzpdkr7",
    "created_at": "2020-05-05T22:17:08.121Z",
    "first_name": "Oliver",
    "last_name": "Fawcett"
  }
}

{
  "success": true,
  "items": [
  {
    "_id": "user_ck9uh3kex000107muemzpdkr7",
    "created_at": "2020-05-05T22:17:08.121Z",
    "first_name": "Oliver",
    "last_name": "Fawcett"
  }
]
}

{
  "success": false,
  "message": "Example error message"
}

All responses are contained in a wrapper object with the key success present.

If success is true, you can expect your result to be found under the item_id, item or items keys depending on whether the result is an ID, an item, or a list of items.

If success is false, you can expect a message key with a description of what went wrong.

Akahu IDs

You may notice that some keys start with an underscore (like _id above). This means that the value is an Akahu ID. Akahu IDs are composed of a prefix denoting the type of ID, and a suffix which is essentially random. For example user_ck9uh3kex000107muemzpdkr7 is a User ID.

Dates and times

Akahu uses ISO 8601 date-time strings for all dates received or sent by the API. We accept timestamps in an any timezone, however all responses are returned in UTC.

Common error messages

Akahu uses the standard HTTP response codes set out here.

Below are some common error messages returned by the Akahu API. In addition to these, each endpoint may return more specific errors which are documented in our API Reference.

400 Bad Request

This response indicates that your request was invalid.

More detail will be provided in the response message. For example:

{
  "message": "payload.amount is a required field"
}

404 Not Found

This response indicates that the specific resource you have requested does not exist (or you do not have permission to access it).

{
  "message": "Not found"
}

401 Unauthorized

This response indicates that we were unable to authenticate your request.

For a user-scoped endpoint (e.g. GET /accounts), this means that the access token provided in the Authorization header is invalid or has been revoked.

For an app-scoped endpoint (e.g. GET /categories), this means that your app credentials provided in the Authorization header are invalid or have been revoked.

{
  "message": "Unauthorized"
}

403 Forbidden

This response indicates that you do not have permission to access the specified resource. This may be due to a number of reasons including:

• Failing to provide the X-Akahu-Id header (required for user-scoped endpoints).
• Attempting to access a resource that your access token isn't scoped for.
• Accessing the API from a disallowed IP address (if IP blocking is configured for your app).
• Certain classes of invalid HTTP requests (e.g. submitting a GET request with a request body).

{
  "message": "Forbidden"
}

429 Too Many Requests

You may be rate-limited in response to a high volume of API requests from your app. If this happens frequently, you may need to reduce the rate at which you send requests to Akahu.

See our reference guide on Rate Limits for more information.

{
  "message": "Your request has been rate limited"
}

500 Internal Server Error

This response indicates that an error occurred in Akahu's system.

{
  "message": "Internal Error"
}