Error Handling
Learn how to handle errors from the API.
Error Structure
Our API returns a consistent error structure for all errors. The API always returns a JSON response with an array of issues
, Onsi Issues always have a code
and a message
.
An exhaustive list can be found lower down.
{
"issues": [
{
"code": "HeaderValidation",
"message": "Required",
"path": "x-api-key"
},
{
"code": "BodyValidation",
"message": "Required",
"path": "currency"
}
]
}
Using the message
field to conditionally handle errors is not recommended as the message
field may change in the
future. Always use the code
field to conditionally handle errors, or any other property in a specific error, like
the row
in an InvalidContent
error.
Error List
Generic
We may introduce more specific error codes to replace the existing generic ones in the future. For now, we recommend treating any generic error codes as a catch-all.
InternalServerError
This is our generic internal server error, this will be returned in cases where an unexpected error occurs
BadRequest
This is our generic bad request error, this will be returned in cases where the request is malformed or invalid and there is no more specific error code to return
A human-readable message used for debugging and logging
Example:
{
"code": "BadRequest",
"message": "The address provided must be based in the United Kingdom"
}
Forbidden
This is our generic forbidden error, this will be returned in cases where the user is not allowed to perform the requested action
A human-readable message used for debugging and logging
Example:
{
"code": "Forbidden",
"message": "You are not allowed to perform this action"
}
NotFound
This is our generic not found error, this will be returned in cases where the requested resource does not exist
A human-readable message used for debugging and logging
Conflict
This is our generic conflict error, this will be returned in cases where the request conflicts with the current state of the server
A human-readable message used for debugging and logging
Request Validation
BodyValidation
An error occurred while validating the request body
A human-readable message used for debugging and logging
QueryValidation
An error occurred while validating the request query parameters
A human-readable message used for debugging and logging
PathValidation
An error occurred while validating the request path parameters
A human-readable message used for debugging and logging
HeaderValidation
An error occurred while validating the request headers
A human-readable message used for debugging and logging
Specific
MemberNotFound
The member could not be found
A human-readable message used for debugging and logging
The unique identifier for a Member, prefixed with mem_
Example:
{
"code": "MemberNotFound",
"message": "The member could not be found",
"memberId": "mem_foo"
}
MemberNotEligible
The member is not eligible to perform the requested action
A human-readable message used for debugging and logging
The unique identifier for a Member, prefixed with mem_
MemberAlreadyInvited
The member has already been invited
A human-readable message used for debugging and logging
The unique identifier for a Member, prefixed with mem_
MemberInsufficientFunds
The member does not have enough funds to perform the requested action
A human-readable message used for debugging and logging
The unique identifier for a Member, prefixed with mem_
BankAccountInvalid
The bank account provided is invalid
A human-readable message used for debugging and logging
FileContent
An error occurred while processing the file content, commonly used for CSV/Ecxel files
A human-readable message used for debugging and logging
The row number in the file where the error occurred
AmountBelowLowerLimit
The requested withdrawal intent amount is below the minimum which can be withdrawn, also returns the minimum amount which can be withdrawn
A human-readable message used for debugging and logging
A monetary value with currency. See Money
Example:
{
"code": "AmountBelowLowerLimit",
"message": "Withdrawal amount is below the lower limit of £10.00",
"lowerLimit": {
"amount": 1000,
"currency": "GBP"
}
}
AmountAboveUpperLimit
The requested withdrawal intent amount is above the maximum which can be withdrawn, also returns the maximum amount which can be withdrawn
A human-readable message used for debugging and logging
A monetary value with currency. See Money
Example:
{
"code": "AmountAboveUpperLimit",
"message": "Withdrawal amount is above the upper limit of £200.00",
"upperLimit": {
"amount": 20000,
"currency": "GBP"
}
}