Errors

In this guide, we will talk about what happens when something goes wrong whilst you work with our API. Mistakes happen, and mostly they will be yours, not ours (hopefully). Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors (hopefully). Therefore, please carefully check your code before contacting SentryPeer support.

Status codes

Here is a list of the different categories of status codes returned by the SentryPeer API. Use these to understand if a request was successful.

Name
2xx
Type
Description
A 2xx status code indicates a successful response. For example, if querying for a phone number or IP address match, you will receive a 200 status code.
Name
4xx
Type
Description
A 4xx status code indicates a client error — this means it's a you problem :)
Name
429
Type
Description
A 429 status code means that you are sending too many requests to the API. Please slow down or upgrade your plan.
Name
5xx
Type
Description
A 5xx status code indicates a server error — you won't be seeing these (if we've done our job right).

Error types

Whenever a request is unsuccessful, the SentryPeer API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

Here is an example list of the error types supported by the SentryPeer API — use these to understand what you have done wrong.

Name
error
Type
Description
This means that you made an error (we hope not).
Name
status
Type
Description
This means that you exceeded your plan's request limit.
Name
message
Type
Description
This is an informational message.

Error response

{
  "error": "Invalid token",
  "reason": "exp"
}

Or if you are using the wrong client to retrieve your bearer token:

Error response

{
    "error": "insufficient_permissions",
    "error_description": "Insufficient claim for the token",
    "message": "Permission denied. Are you using the correct client_id to generate your token?"
}

Rate limiting

The SentryPeer API is rate-limited to prevent abuse. If you exceed your plan's request limit, you will receive a 429 status code. You can upgrade your plan to increase your request limit.

If you are receiving a 429 status code, please upgrade your plan or contact support.

You can see your current plan's request limit by visiting the pricing page or looking at the response headers on your API requests:

Response headers on the Tester Plan

ratelimit-limit: 5
ratelimit-policy: 5;w=3600;policy="leaky bucket"
ratelimit-remaining: 3
ratelimit-reset: 3575

We follow the RateLimit header fields for HTTP RFC draft specification.

429 response

{
  "status": "429 Too Many Requests"
}