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

string

required

string

required

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

string

required

string

required

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

string

required

string

required

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

string

required

string

required

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

string

required

string

required

A human-readable message used for debugging and logging

RateLimitExceeded

The request was rate limited

string

required

string

required

A human-readable message used for debugging and logging

UnprocessableEntity

This is our generic unprocessable entity error, this will be returned in cases where the request is valid but cannot be processed due to business logic or other constraints

string

required

string

required

A human-readable message used for debugging and logging

Request Validation

BodyValidation

An error occurred while validating the request body

string

required

string

required

A human-readable message used for debugging and logging

string

required

QueryValidation

An error occurred while validating the request query parameters

string

required

string

required

A human-readable message used for debugging and logging

string

required

PathValidation

An error occurred while validating the request path parameters

string

required

string

required

A human-readable message used for debugging and logging

string

required

HeaderValidation

An error occurred while validating the request headers

string

required

string

required

A human-readable message used for debugging and logging

string

required

Specific

MemberNotFound

The member could not be found

string

required

string

required

A human-readable message used for debugging and logging

string

required

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

string

required

string

required

A human-readable message used for debugging and logging

string

required

The unique identifier for a Member, prefixed with mem_

MemberAlreadyInvited

The member has already been invited

string

required

string

required

A human-readable message used for debugging and logging

string

required

The ID of the member who already exists in the system

MemberInsufficientFunds

The member does not have enough funds to perform the requested action

string

required

string

required

A human-readable message used for debugging and logging

string

required

The unique identifier for a Member, prefixed with mem_

BankAccountInvalid

The bank account provided is invalid

string

required

string

required

A human-readable message used for debugging and logging

FileContent

An error occurred while processing the file content, commonly used for CSV/Ecxel files

string

required

string

required

A human-readable message used for debugging and logging

string

required

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

string

required

string

required

A human-readable message used for debugging and logging

object

required

A monetary value with currency. See Money

Show properties

string

required

Price in lowest denomination of currency (e.g. cents)

string

required

ISO 4217 currency code

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

string

required

string

required

A human-readable message used for debugging and logging

object

required

A monetary value with currency. See Money

Show properties

string

required

Price in lowest denomination of currency (e.g. cents)

string

required

ISO 4217 currency code

Example:

{
  "code": "AmountAboveUpperLimit",
  "message": "Withdrawal amount is above the upper limit of £200.00",
  "upperLimit": {
    "amount": 20000,
    "currency": "GBP"
  }
}

InvalidAddMemberPayload

The payload provided to add a member is invalid

string

required

string

required

A human-readable message used for debugging and logging

string

required

The email provided to add a member

InvalidUpdateMemberPayload

The payload provided to update a member is invalid

string

required

string

required

A human-readable message used for debugging and logging

string

required

The unique identifier for a Member, prefixed with mem_

InvalidRemoveMemberPayload

The payload provided to remove a member is invalid

string

required

string

required

A human-readable message used for debugging and logging

string

required

The unique identifier for a Member, prefixed with mem_

Get Started

Member Management

On Demand Pay

Schemas

Error Handling

Error Structure

Error List

Generic

InternalServerError

BadRequest

Forbidden

NotFound

Conflict

RateLimitExceeded

UnprocessableEntity

Request Validation

BodyValidation

QueryValidation

PathValidation

HeaderValidation

Specific

MemberNotFound

MemberNotEligible

MemberAlreadyInvited

MemberInsufficientFunds

BankAccountInvalid

FileContent

AmountBelowLowerLimit

AmountAboveUpperLimit

InvalidAddMemberPayload

InvalidUpdateMemberPayload

InvalidRemoveMemberPayload

​Error Structure

​Error List

​Generic

​InternalServerError

​BadRequest

​Forbidden

​NotFound

​Conflict

​RateLimitExceeded

​UnprocessableEntity

​Request Validation

​BodyValidation

​QueryValidation

​PathValidation

​HeaderValidation

​Specific

​MemberNotFound

​MemberNotEligible

​MemberAlreadyInvited

​MemberInsufficientFunds

​BankAccountInvalid

​FileContent

​AmountBelowLowerLimit

​AmountAboveUpperLimit

​InvalidAddMemberPayload

​InvalidUpdateMemberPayload

​InvalidRemoveMemberPayload

Error Structure

Error List

Generic

InternalServerError

BadRequest

Forbidden

NotFound

Conflict

RateLimitExceeded

UnprocessableEntity

Request Validation

BodyValidation

QueryValidation

PathValidation

HeaderValidation

Specific

MemberNotFound

MemberNotEligible

MemberAlreadyInvited

MemberInsufficientFunds

BankAccountInvalid

FileContent

AmountBelowLowerLimit

AmountAboveUpperLimit

InvalidAddMemberPayload

InvalidUpdateMemberPayload

InvalidRemoveMemberPayload