Errors · Easyflow API

The API uses HTTP status codes to indicate whether a request succeeded. Codes in the 2xx range mean success, 4xx codes point to a problem with the request, and 5xx codes mean that something went wrong on Easyflow.

Status codes

Status	Meaning	What to do
`200`	The request succeeded.	Read the result in the response body.
`400`	A parameter is missing or invalid.	Check the message, fix the request and send it again.
`401`	The credentials are missing or invalid.	Check the `x-api-key` and `x-api-secret` headers.
`403`	The credentials cannot access the resource.	Check the `business-id` header and the permissions of your account.
`409`	The request conflicts with the current state of a resource, for example because it already exists.	Check the message, fetch the current state of the resource and decide whether to send a different request.
`422`	The request is valid but cannot be processed.	Check the message before trying again.
`429`	Too many requests were sent in a short period.	Wait the number of seconds in the `Retry-After` header and send the request again.
`500`	Unexpected error on the server.	Wait a moment and try again.

Error format

Error responses have these fields:

Field	Type	Description
`message`	string	Explanation of the error.
`error`	string	Name of the HTTP status. Not present in `429` and `500` responses.
`statusCode`	integer	HTTP status code.
`errorCode`	string	Code that identifies the error. Present only on some errors.

{
  "message": "Invalid param: []",
  "error": "Bad Request",
  "statusCode": 400
}

For 400 errors, the brackets of the message usually contain the name of the invalid parameter, for example Invalid param: [amountToBePaidInCents].

Examples

{
  "message": "Unauthorized",
  "error": "Unauthorized",
  "statusCode": 401
}

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403
}

{
  "message": "Conflict",
  "error": "Conflict",
  "statusCode": 409
}

{
  "message": "Unprocessable Entity",
  "error": "Unprocessable Entity",
  "statusCode": 422
}

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Handling errors

Check the HTTP status before reading the body, and handle each range differently.
Do not retry 400, 401, 403, 409 and 422 errors without changing the request, because the result will usually be the same. The exception is a 409 or 422 that the page of the endpoint describes as temporary: in that case, follow the page of the endpoint and send the same request again, with the same headers and body.
When you receive a 429 error, wait the number of seconds in the Retry-After header before sending the request again.
Retry 500 errors a few times with an increasing interval between attempts.
When a response has an errorCode, use it instead of the text of message to identify the error in your code.
Log the message of unexpected errors to make troubleshooting easier.