Errors

When a request fails, the API responds with an HTTP error status and a JSON body you can use to decide what to do next.

You can tell if your request was successful by checking the HTTP status code. On failure, read title and message from the body before contacting support.

Most reported errors come from incorrect API usage or invalid parameters. Check your request against the relevant reference page before contacting Aella support.

Status codes

Name
2xx
Description
The request succeeded.
Name
4xx
Description
A client error — validate your parameters, authentication, or IP whitelist.
Name
5xx
Description
A server error. Retry with backoff and contact support if it persists.

Error response shape

Unsuccessful responses use this envelope. The global error filter returns status as the string "error", plus a short title and a human-readable message.

Name
status
Type
string
Description
Always "error" on failure.
Name
title
Type
string
Description
Short category such as "Request Validation", "Not found", or "Something went wrong".
Name
message
Type
string
Description
Human-readable explanation of what failed.

Common HTTP statuses you will see:

Name
400
Description
Validation or bad request. title is often "Request Validation".
Name
401
Description
Missing or invalid secret key.
Name
403
Description
Authenticated but not allowed — for example an IP that is not whitelisted.
Name
404
Description
No matching record.
Name
429
Description
Too many requests. Wait and retry.

Error response

{
  "status": "error",
  "title": "Request Validation",
  "message": "Invalid account number provided"
}

Successful responses

Successful merchant endpoints return:

Success response

{
  "success": true,
  "message": "Request successful",
  "data": {},
  "status": 200
}

Paginated endpoints may also include a meta object. See the endpoint reference for the exact meta fields on that route.