Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API.

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. Therefore, please carefully check your code before contacting OneSend support.

Status codes

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

Name
2xx
Description
A 2xx status code indicates a successful response.
Name
401
Description
A status of 401 indicates missing authentication, you most likely forgot to add the Authorization: ProjectKey {token} header.
Name
403
Description
A status of 403 means access denied. You're trying to access a resource you do not have permission for.
Name
422
Description
A status of 422 indicates a validation error. Some of the values you have passed are not correct. When receiving this kind of error you'll always have a list of violations telling you what's wrong.
Name
429
Description
A status of 429 means you have exceeded the rate limit for the given resource and should slow down a bit.
Name
502
Description
A status of 502 indicates that the service is temporarily unavailable, you should try again in a few seconds.
Name
5xx
Description
Any other 500 type error means something went wrong on our side, we'll be notified and will try to fix it as soon as possible.

Error types

Whenever a request is unsuccessful, the OneSend 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's an example of an API call that didn't pass validation.

Error response

{
  "status": 422,
  "detail": "There was an error during validation",
  "title": "An error occurred"
  "type": "/validation_errors/0=c1051bb4-d103-4f74-8988-acbcafc7fdc3;1=c1051bb4-d103-4f74-8988-acbcafc7fdc3"
  "detail": "to: This value should not be blank.\nmessage: This value should not be blank."
  "violations": [
       {
            "propertyPath": "to",
            "message": "This value should not be blank.",
            "code": "c1051bb4-d103-4f74-8988-acbcafc7fdc3"
       },
       {
           "propertyPath": "message",
           "message": "This value should not be blank.",
           "code": "c1051bb4-d103-4f74-8988-acbcafc7fdc3"
      }
  ]
}