Response Formatting¶

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",
    "created_at": "2020-05-05T22:17:08.121Z",
    "first_name": "Oliver",
    "last_name": "Fawcett-Griffiths",
    "access_expires_at": "2021-06-07T20:32:16.221Z"
  }
}

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 or items keys.

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.

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.

404 Not Found¶

This response indicates that the resource you have specified does not exist.

{
  "message": "Not found"
}

401 Unauthorized¶

This response indicates that you do not have permission to view the specified resource. If you see this response, check to make sure you are sending the correct Authorization header, and possibly X-Akahu-ID header.

{
  "message": "Unauthorized"
}

403 Forbidden¶

This response also indicates that you do not have permission to view the specified resource. If you see this response, check to make sure you are sending the correct Authorization header, and possibly X-Akahu-ID header.

{
  "message": "Forbidden"
}

500 Internal Server Error¶

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

{
  "message": "Internal Error"
}