Reference

Errors

The KOI partner API uses HTTP status codes and a JSON body. Callback errors you return to KOI are covered in Refusing a transaction.

Response format

json

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

Field	Type	Description
`statusCode`	number	HTTP status code.
`message`	string	Human-readable reason. Do not parse it; it can change.
`error`	string	HTTP reason phrase. Not always present.

422 Unprocessable Entity lists the invalid fields and their messages:

json

{
  "user_id": ["user_id is a required field"],
  "game": ["game is a required field"]
}

Status	Meaning	What to do
`200`	Success.	—
`400`	The request is valid JSON but cannot be processed (unknown currency, inconsistent dates, missing configuration).	Fix the request or the account configuration.
`401`	Missing or invalid access token, or the resource is not available to your account.	Check the `Authorization` header and the enabled games.
`403`	The operation is not allowed for your account.	Contact your account manager.
`404`	The resource does not exist in your account.	Check the identifier.
`422`	Field validation failed.	Fix the listed fields.
`500`	Unexpected error in KOI.	Retry with backoff. Report persistent failures with the time and request.
`502`	Your own endpoint, called by KOI on your behalf, failed.	Check your wallet endpoint.

KOI never returns stack traces, database errors or third-party responses in an error body.