Skip to content

Responses and error codes ​

Every endpoint answers with the same JSON envelope, except Downloading contributions as CSV, which answers with a file.

Envelope ​

json
{
  "status": {
    "code": 0,
    "name": "Ok"
  },
  "data": {}
}
FieldDescription
status.code0 for success. Any other value is an error code from the table below. It is not the HTTP status.
status.nameOk for success, otherwise the name of the error.
status.messagePresent on errors only. A text for people. Do not parse it.
dataThe result. It is always present. On errors it is null, a text with details of a validation failure, or an object: the sign-in answer with code 80 lists the second sign-in steps of the account in it.

The HTTP status of a successful response is 200. On errors the HTTP status is the one listed with the error code.

An error looks like this:

json
{
  "status": {
    "code": 4,
    "name": "InvalidBearer",
    "message": "Request does not contain `Authorization` header"
  },
  "data": null
}

Decide on status.code together with the HTTP status. Do not rely on status.message.

Authorization header ​

Every endpoint except Sign in needs the header:

http
Authorization: Bearer <accessToken>

Refresh the tokens takes the refreshToken in the same form.

Error codes ​

Session and access ​

HTTPCodeNameMeaning
4012InvalidSignatureSign-in: the signature does not match, or the public key is not the one registered for the user. Other endpoints: the signature of the token is not valid.
4043UserNotFoundNo user with this email address.
4014InvalidBearerThe Authorization header is missing, is not Bearer <token>, or the session of the token has ended.
4015InvalidRefreshTokenThe refresh token is not valid or its session has ended.
4016TokenExpiredThe token has expired. Refresh the tokens or sign in again.
42217InvalidTokenThe token could not be read.
42218InvalidPublicKeyauthPublicKeyHex is not a 32-byte Hex string.
42219SignatureDecodeErrorsignature is not a Hex string.
40359AccessDeniedErrorThe user is blocked or not yet approved, or asks for data of another company or user.
42863TwoFactorAuthenticationCodeMissingErrorA second step is on and the request carries no code. A code was emailed earlier and is still valid, or method is totp and authCode is missing.
42264TwoFactorInvalidAuthenticationTokenErrorThe code is wrong.
42865TwoFactorAuthenticationMissingButNotifiedErrorA second step is on and the request carries no code. A code has just been emailed.
40975TwoFactorAuthenticationStatusErrorSign-in: the request names a sign-in method that is not set up for the account.
42880TwoFactorRequiredErrorSign-in: the account has an authenticator app or a passkey as its second step. data is an object with the methods of the account. Repeat the request with method and authCode.

Requests ​

HTTPCodeNameMeaning
40011ArgumentNotValidA value has the wrong form, for example an identifier that is not a phone number, IP address, IMEI, email address or URL, a range that runs backwards, or a date that is not ISO 8601.
40012MessageNotReadableThe body is not the expected JSON, a required field is missing, or fraudType is unknown.
40049MalformedParametersErrorA query parameter has the wrong type or an unknown value.
5001InternalErrorThe request failed on the server. Retry later; if it persists, contact support.

Contributions ​

HTTPCodeNameMeaning
4009UnknownFraudTypeErrorThe fraud type code in a transaction is unknown.
40015InvalidTransactionThe transaction cannot be read or applied. Also returned when a request carries more than 5000 entries.
40016InvalidInstructionTypeThe identifier does not fit the fraud type, or the transaction is not one this endpoint takes.
40432AssetDefinitionNotFoundErrorNo contribution with this assetDefinitionId.
40036DuplicateErrorA record identifier of the transaction is already in use. Assemble the contribution again.
40038PrivilegedContributionModificationErrorA privileged contribution cannot be flagged.
40443PeerNotFoundErrorThe company of the user was not found.
40348NotEnoughCreditsErrorThe balance changed while the request was served. Repeat the request.
40054InvalidContributionCountryCodeErrororigination or destination is not a known country code.
40460ContributionNotFoundErrorNo active contribution matches.
40961ExpiredContributionFlagErrorThe contribution has expired or is already flagged.
40070ContributionSourceErrorsourcePeerId is blank or is not a registered company.
40379DomainLimitExceededErrorThe upload would exceed the upload limit of the company. Nothing is stored.

Configuration not available ​

These mean the platform is not ready to serve the request. Retry later; if it persists, contact support.

HTTPCodeName
50324TriggerNotFoundError
40427MetadataKeyNotFoundError
40028IncorrectMetadataError
50334RewardsTableNotSetError
50357ContributionPricesNotSetError
50366ContributionTimeToLiveTableNotSetError
50373ContributionRewardSplitRatioNotSetError

Codes these endpoints do not return ​

Codes 13 (MissingRequestParam), 14 (Forbidden) and 77 (IncorrectContributionTypeError) exist on the Exchange but are not returned by the endpoints of this reference.