HTTP status codes

When your application communicates with the Cint Exchange API, every response it receives includes an HTTP status code. This code is a crucial piece of information, providing immediate feedback on whether your request was successful, if there was an issue with the information you sent, or if a problem occurred on Cint's servers. Understanding these codes will help you build a more robust and resilient integration.

HTTP status codes are grouped into classes, indicated by the first digit:

• 2xx (Success): This means we received, understood, and processed your request successfully.
• 4xx (Client Error): The request you sent was flawed in some way.
• 5xx (Server Error): Something went wrong on Cint's end.

---

Successful requests: the 2xx series

When an API call is successful, you will receive a status code in the 200s.

• 200 OK: This is the standard response for a successful request. For example, when you successfully retrieve a project's details, the API will respond with a 200 OK status and the requested data in the response body.

• 204 No Content: This code indicates that the server successfully processed your request but has no information to send back in the response body. You'll often see this after a successful PUT request to update an entity or a POST request to launch a target group, as the primary confirmation is the success of the operation itself.

Example of a successful POST request to create a project:

curl -X "POST" "https://api.cint.com/v1/demand/accounts/{account_id}/projects" \
     -H 'Authorization: Bearer <YOUR_JWT>' \
     -H 'Content-Type: application/json' \
     -H 'idempotency-key: <YOUR_IDEMPOTENCY_KEY>' \
     -d '{
  "name": "Test Project",
  "project_manager_id": "<YOUR_PROJECT_MANAGER_ID>"
}'

A successful creation will return a 200 OK or similar success code, along with the ID of the newly created project in the response body.

{
  "id": "01K40T69E63BHTT9MAJYRBQ8HY"
}

---

Client-Side Errors: The 4xx Series

If you receive a 4xx error, it means the problem lies with the request your application sent. You should check the request for errors before retrying.

• 400 Bad Request: This is a general-purpose error indicating that the server could not understand your request due to invalid syntax. This could mean a missing required field, an incorrectly formatted parameter, or other issues with the structure of your request. The API response body will often contain more specific details about what went wrong.

Example of a 400 Bad Request response:

{
  "object": "bad_request_error",
  "detail": "request had validation errors",
  "invalid_params": [
    {
      "name": "Name",
      "reason": "'Name' must not be empty."
    }
  ]
}

• 401 Unauthorized: This error occurs when your request lacks valid authentication credentials. This usually means your JSON Web Token (JWT) is missing, expired, or invalid. You will need to request a new token before proceeding.

Example of a 401 Unauthorized response:

{
  "id": "fe68cdd2-ee87-4dbf-8950-63c5cbca94c7",
  "object": "authorization_error",
  "detail": "you don't have the right permissions to perform this operation"
}

• 403 Forbidden: This code indicates that the server understood the request, but is refusing to fulfill it. This is not an authentication issue but rather a permissions issue. For example, the user associated with your credentials may not have the necessary permissions to perform the requested action.

• 404 Not Found: This familiar error means that the resource you're trying to access doesn't exist. For instance, if you try to retrieve a project with an ID that doesn't correspond to any existing project, you will receive a 404 Not Found error.

Example of a 404 Not Found response:

{
  "object": "not_found_error",
  "detail": "project_id: the specified resource was not found"
}

---

Server-Side Errors: The 5xx Series

A 5xx error indicates that a problem occurred on the Cint Exchange servers. While these errors are less common, your integration should be prepared to handle them.

• 500 Internal Server Error: This is a generic error message indicating an unexpected condition on the server that prevented it from fulfilling the request. If you consistently receive this error, it is best to check the Cint status page for any ongoing incidents or contact support for assistance.

• 503 Service Unavailable: This code means that the server is temporarily unable to handle the request, perhaps due to being overloaded or down for maintenance. It's generally a temporary condition, and you should try the request again after a short delay.

You can check our Status Page to ensure our systems are functioning as expected.

By correctly interpreting these status codes, you can build more effective error-handling logic into your application, leading to a smoother and more reliable integration with the Cint Exchange.