Response Formats
Akahu returns API responses in a standard format, described here.
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"
}
Updated 4 months ago