Zendesk API Integrations

Status Codes

Responses may have the status codes described in the following sections.

200 range

The request was successful. The status is 200 for successful GET and PUT requests, 201 for most POST requests, and 204 for DELETE requests.

400 range

The request was not successful. The content type of the response may be text/plain for API-level error messages such as trying to call the API without SSL. The content type is application/json for business-level error messages because the response includes a JSON object with information about the error:

{
  "details": {
    "value": [
      {
        "type": "blank",
        "description": "can't be blank"
      },
      {
        "type": "invalid",
        "description": " is not properly formatted"
      }
    ]
  },
  "description": "RecordValidation errors",
  "error": "RecordInvalid"
}

If you see a response from a known endpoint that looks like plain text, you probably made a syntax error in your request. This type of response commonly occurs when making a request to a nonexistent Zendesk Support instance.

403

A 403 response means the server has determined the user or the account doesn’t have the required permissions to use the API.

409

A 409 response indicates a conflict with the resource you're trying to create or update.

409 errors typically occur when two or more requests try to create or change the same resource simultaneously. While Zendesk APIs can handle concurrent requests, requests shouldn't change the same resource at the same time. To avoid 409 errors, serialize requests when possible. If you receive a 409 error, you can retry your request after resolving the conflict.

The Zendesk Ticketing API provides specific parameters to prevent conflicts when updating tickets. For more information, see Protecting against ticket update collisions.

422 Unprocessable Entity

A 422 response means that the content type and the syntax of the request entity are correct, but the content itself is not processable by the server. This is usually due to the request entity not being relevant to the resource that it's trying to create or update. Example: Trying to close a ticket that's already closed.

429

A 429 error indicates that a usage limit has been exceeded. See the Zendesk Rate limits.

500 range

If you ever experience responses with status codes in the 500 range, the Zendesk API may be experiencing internal issues or having a scheduled maintenance during which you might receive a 503 Service Unavailable status code.

A 503 response with a Retry-After header indicates a database timeout or deadlock. You can retry your request after the number of seconds specified in the Retry-After header.

If the 503 response doesn't have a Retry-After header, Zendesk Support may be experiencing internal issues or undergoing scheduled maintenance. In such cases, check @zendeskops and our status page for any known issues.

When building an API client, we recommend treating any 500 status codes as a warning or temporary state. However, if the status persists and if Zendesk doesn't have a publicly announced maintenance or service disruption, contact the Zendesk Customer Support.

If submitting a ticket to Zendesk, provide the X-Zendesk-Request-Id header included in the HTTP response. This helps the Support team track down the request in the logs more quickly.