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": {}
}| Field | Description |
|---|---|
status.code | 0 for success. Any other value is an error code from the table below. It is not the HTTP status. |
status.name | Ok for success, otherwise the name of the error. |
status.message | Present on errors only. A text for people. Do not parse it. |
data | The 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
| HTTP | Code | Name | Meaning |
|---|---|---|---|
401 | 2 | InvalidSignature | Sign-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. |
404 | 3 | UserNotFound | No user with this email address. |
401 | 4 | InvalidBearer | The Authorization header is missing, is not Bearer <token>, or the session of the token has ended. |
401 | 5 | InvalidRefreshToken | The refresh token is not valid or its session has ended. |
401 | 6 | TokenExpired | The token has expired. Refresh the tokens or sign in again. |
422 | 17 | InvalidToken | The token could not be read. |
422 | 18 | InvalidPublicKey | authPublicKeyHex is not a 32-byte Hex string. |
422 | 19 | SignatureDecodeError | signature is not a Hex string. |
403 | 59 | AccessDeniedError | The user is blocked or not yet approved, or asks for data of another company or user. |
428 | 63 | TwoFactorAuthenticationCodeMissingError | A 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. |
422 | 64 | TwoFactorInvalidAuthenticationTokenError | The code is wrong. |
428 | 65 | TwoFactorAuthenticationMissingButNotifiedError | A second step is on and the request carries no code. A code has just been emailed. |
409 | 75 | TwoFactorAuthenticationStatusError | Sign-in: the request names a sign-in method that is not set up for the account. |
428 | 80 | TwoFactorRequiredError | Sign-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
| HTTP | Code | Name | Meaning |
|---|---|---|---|
400 | 11 | ArgumentNotValid | A 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. |
400 | 12 | MessageNotReadable | The body is not the expected JSON, a required field is missing, or fraudType is unknown. |
400 | 49 | MalformedParametersError | A query parameter has the wrong type or an unknown value. |
500 | 1 | InternalError | The request failed on the server. Retry later; if it persists, contact support. |
Contributions
| HTTP | Code | Name | Meaning |
|---|---|---|---|
400 | 9 | UnknownFraudTypeError | The fraud type code in a transaction is unknown. |
400 | 15 | InvalidTransaction | The transaction cannot be read or applied. Also returned when a request carries more than 5000 entries. |
400 | 16 | InvalidInstructionType | The identifier does not fit the fraud type, or the transaction is not one this endpoint takes. |
404 | 32 | AssetDefinitionNotFoundError | No contribution with this assetDefinitionId. |
400 | 36 | DuplicateError | A record identifier of the transaction is already in use. Assemble the contribution again. |
400 | 38 | PrivilegedContributionModificationError | A privileged contribution cannot be flagged. |
404 | 43 | PeerNotFoundError | The company of the user was not found. |
403 | 48 | NotEnoughCreditsError | The balance changed while the request was served. Repeat the request. |
400 | 54 | InvalidContributionCountryCodeError | origination or destination is not a known country code. |
404 | 60 | ContributionNotFoundError | No active contribution matches. |
409 | 61 | ExpiredContributionFlagError | The contribution has expired or is already flagged. |
400 | 70 | ContributionSourceError | sourcePeerId is blank or is not a registered company. |
403 | 79 | DomainLimitExceededError | The 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.
| HTTP | Code | Name |
|---|---|---|
503 | 24 | TriggerNotFoundError |
404 | 27 | MetadataKeyNotFoundError |
400 | 28 | IncorrectMetadataError |
503 | 34 | RewardsTableNotSetError |
503 | 57 | ContributionPricesNotSetError |
503 | 66 | ContributionTimeToLiveTableNotSetError |
503 | 73 | ContributionRewardSplitRatioNotSetError |
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.