Handling API Responses

When an API request succeeds, the HTTP status of the response will be 2xx. All other HTTP status codes indicate that there was an error with the request.

We closely follow the HTTP specification and return relevant HTTP status codes. Additionally, the body of the response will contain valid JSON with further description of the error.

• Handling long-running operations
• Working within API rate limits
• Other error responses

Handling long-running operations

Some API operations in Capsule are potentially long running or might be scheduled to be executed later. We don't want the API integrations to wait on a response when performing these actions so we return HTTP status code 202 Accepted to let you know that “we got your request, but it’s not getting processed at this exact moment.”

For example, deleting a tag can return this response:

The response includes a URL in the Location header. A GET request to this link will return the status of the job, so, if required, you may keep track of the progress.

Response

{
  "job": {
    "status": "completed",
    "progress": 100,
    "action": "Deleting Tag",
    "id": "02ae8e16-9199-426c-9984-6362b08f8555"
  }
}

Working within API rate limits

For requests using Bearer Token Authentication, each Capsule user can make up to 4,000 requests per hour.

All successful API requests will include the following three headers with details about the current rate limit status:

• X-RateLimit-Limit - The maximum number of requests that the user is allowed to make per hour.
• X-RateLimit-Remaining - The number of requests remaining in the current rate limit window.
• X-RateLimit-Reset - The time at which the current rate limit window resets in UTC epoch seconds.

Response

Once you go over the rate limit, all API requests will receive an error response until the rate limit quota is reset:

{
  "error":"rate limit reached"
}

After receiving such a response, your application should wait until the time inside the X-RateLimit-Reset header before it makes any other API requests for the specific user.

If you repeatedly continue to make API requests after reaching the rate limit and this causes excessive load, we may temporarily block the application or disable the user account to prevent affecting other users of the system.

Avoiding the rate limit

If you are exceeding the rate limit, you can likely fix the issue by just throttling all API requests. We recommend adding a one second delay between API requests.

You can also avoid the rate limit by caching the API responses. The since query parameter and the /api/v2/{type}/deleted endpoints allows to keep your local version up to date with the Capsule version.

Including ?since={date} query parameter in list parties, list opportunities and list cases requests will retrieve only entities added or updated after the specified date (UTC timezone). The date must in be ISO8601 format, eg. Midnight July 31, 2016 GMT would be 2016-07-31T00:00:00Z.

You can also retrieve parties that were deleted after a specific date using the list deleted parties endpoint. This will return a list of party ids that were deleted from Capsule so you can remove them from your local database or cache. Similar endpoints are available for opportunities and cases.

If you’re already using these features and are still frequently exceeding your rate limit, please contact us.

Other error responses

Here we will cover only the most common error responses. You can find a full list of HTTP status code and their description on Wikipedia.

400 Bad Request

Capsule failed to process the body of your request. Generally, this will be returned if the body does not contain JSON or the name of the root field is incorrect (e.g. sending a party object to an endpoint that expects an opportunity).

The following example will always produce an error because of an invalid json object in the body submitted to the API.

curl -H "Authorization: Bearer {token}" -H "Content-type:application/json" -i
-d "<organisation><name>This is not the JSON you are looking for</name></organisation>" https://api.capsulecrm.com/api/v2/parties

{
    "message": "Invalid JSON format"
}

422 Validation Failed

Capsule successfully parsed your request, however, the request did not execute because a field validation failed (e.g. trying to create an organisation without a name). The body of the response will contain more details about why the validation failed.

{
  "message": "Validation Failed",
  "errors": [
    {
      "message": "name is required",
      "resource": "party",
      "field": "name"
    }
  ]
}

401 Authentication Failed

You did not include a correct Authorization header or the bearer token is invalid or expired. You can check the body (or WWW-Authenticate header) for the exact reason of the failure.

{
  "message": "Requires authentication"
}

403 Forbidden

You included a correct Authorization header, but you don't have permission to perform the requested operation.

You will get this response if you try to write to the API, but the provided token is only "read" scope or if you try to perform an operation that requires admin privileges (e.g. update a user's email address) as a non-admin user.

{
  "message": "Requires additional scope"
}