Status Codes

How you know whether your request succeeded.

What are status codes?

When you make an API request, our response will include an HTTP status code. These are standard responses web services may give to their clients' requests to indicate success or failure.

Let's say you made a request to create a new note:

curl --request POST \
  --url \
  --data '{"customer_id":1001,"body":"This is a test note."}'

And got this response:

HTTP/1.1 201 Created
Content-Type: application/json
Server: Microsoft-IIS/8.5
X-Powered-By: ASP.NET
Date: Thu, 22 Feb 2018 20:55:57 GMT
Connection: close
Content-Length: 228
X-Frame-Options: SAMEORIGIN

    "ok": true,
    "id": 11027

The first line, "HTTP/1.1 201 Created", contains the status code: 201. This code indicates your request was successful, and your note was created. (You can see the details of the new note in the body of the response.)

We've listed the different types of codes we return below.


200-level status codes (codes from 200 to 299) indicate your request was successfully received, understood, and processed.

Status CodeMessageExplanation
200OKResult of a successful request.
201CreatedResult of a successful request to create a new resource.

Client error

400-level status codes usually indicate you or your API client made an error.

Status CodeMessageExplanation
400Bad RequestThe request was unacceptable, often due to missing a required parameter.
401UnauthorizedYou are not authenticated or authentication failed.
403ForbiddenYou don't have permission to perform an action or access a resource.
404Not FoundYou requested a resource that doesn't exist.
405Method Not AllowedYou used an HTTP method we don't allow. (For example, you POSTed to /reports/1234/result, and POST is not supported for this resource.)

Server error

500-level status codes usually indicate we made an error or can't fulfill your request.

Status CodeMessageExplanation
500Server ErrorAn error occurred on our side.
501Not ImplementedYou used an HTTP method we currently don't allow, but we will allow it in the future. (For example, you POSTed to /payments, and we haven't implemented POST for that resource yet.)
503Service UnavailableWe currently can't handle your request. We may be performing maintenance, or we might have received too many requests to process at once.
504Gateway TimeoutA gateway or proxy server didn't get a response quickly enough. This probably means one of our systems or our Internet service provider (ISP)'s systems is having issues. There could also be a problem with your proxy or ISP.

What’s Next

Status codes sometimes tell you everything you need to know, but we often provide more detailed content in the body of our responses.