Responses

All responses return conventional HTTP status codes. Most of the responses (GET, POST, PATCH/PUT) also return objects in the JSON format.

CarrierX API allows cross-origin (CORS) requests and data transfers.

HTTP Status Codes

Error Code	Message	Description
2xx	Success
200	OK	The request has succeeded. The result will be a returned JSON object or a link to download a file.
201	Created	The request has succeeded and led to the creation of a resource. This response is normally returned to the requests that upload files.
204	No Content	The server has successfully fulfilled the request. There is no additional content to send in the response payload body. This response code is normally returned to the DELETE requests.
4xx	Client Errors
400	Bad Request	The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications.
400	No JSON object could be decoded	Generally an indicator that there is a syntax error.
401	Bad credentials	The request requires correct user authentication.
401	Unauthorized	The request requires user authentication.
403	Forbidden	The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated.
404	Cannot find item by SID	The SID number does not exist. Verify that the SID has been entered correctly. Note that calls can expire.
404	Not Found	The requested resource was not found on the server.
409	Depends on the conflict source	This status code (aka Conflict) means that your request could not be processed because of some conflict that has occurred during such a request. For specific details see the error section of the API method that you are calling. As a rule, you can try to resolve the conflict by resubmitting your request later.
415	Unsupported media type	Ensure that the header includes support for the JSON content type.
422	Object validation error	The server cannot process a request to the API because the request contains semantic errors or does not meet certain conditions.
5xx	Server Errors
500	Internal server error	The server encountered an unexpected condition which prevented it from fulfilling the request.

Examples

A typical 200 status code in the response

HTTP/2 200
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Credentials,Content-Disposition,Access-Control-Allow-Headers
Content-Length: 1333
Content-Type: application/json
Date: Wed, 22 Sep 2025 08:23:06 GMT
Server: nginx
Strict-Transport-Security: max-age=31536000; includeSubDomains
Vary: accept-encoding

CarrierX API uses the following HTTP status codes:

A sample 400 status code when the JSON sent in the request body has errors in its syntax:

{
    "body": {
        "message": "cannot parse json. Check json for validity",
        "errors": null
    },
    "status": 400
}

A sample 401 status code when trying to send a request without authentication:

{
  "message": "authentication required",
  "errors": [
    {
      "field": "cause",
      "message": "authentication required",
      "reference_sid": null
    }
  ]
}

A sample 403 status code when trying to access resources you do not have enough permission for:

{
    "message": "permission denied",
    "errors": [
        {
            "field": "cause",
            "message": "permission denied",
            "reference_sid": null
        }
    ]
}

A sample 404 status code when trying to access a non-existent object (e.g., a token with an incorrect SID):

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find token",
            "reference_sid": null
        }
    ]
}

Response Objects

A typical formatted JSON object in the response

{
    "callback_url": null,
    "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

Successful requests return objects in the JSON format with application/json set as Content-Type. The object keys and values depend on the request and the object returned, and are described in the corresponding object sections.

Normally, the system returns the object fields unordered and unformatted. To view the object fields ordered alphabetically and "pretty-formatted" in the response to the command-line requests (e.g., cURL), use the jq command-line JSON processor or similar tools.

With jq, the request will look like this:

curl -X GET 'https://api.carrierx.com/core/v2/oauth/whoami' -H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda' | jq -S