When an error occurs on the Payman API, the response status code will be set in the 4xx or 5xx range. Additionally, the response body will contain a JSON object with further information about the error. The json will have the format:

{
  status: number, // The HTTP response status code
  timestamp: string, // The timestamp at which the erro occurred
  errorCode: string, // A more detailed reason for the error (see below for some common codes)
  errorMessage: string, // Any additional descriptive text around the error and its cause
  context: Map<string, any>, // A list of contextual information - this will contain things like IDs to which the error relates, etc
  traceId: string // an internal ID for tracing the error
}

​
Common Error Codes

The Payman system will attempt to provide context around why an error code was received. Some common codes include:

  • invalid_payload - something about the request payload is invalid, or the system is in the wrong state to accept this payload. The errorMessage and context will provide more details.
  • insufficient_funds - there weren’t enough funds in the wallet to perform the requested action
  • validation_error - a field in your payload has an invalid value
  • entity_already_exists - a conflicting entity already exists in the system
  • entity_not_found - the entity you’re looking for couldn’t be found
  • not_authorized - the authentication credentials provided are not valid or are missing
  • not_allowed - you are attempting to perform an action to which you do not have the requisite permissions on the system
AuthenticationPagination