API Status Codes

Response status codes (http) provide insight into the outcome of your AgentSync API request:

• 2xx – SuccessIndicates that the request was successful.
• 4xx – Client ErrorIndicates an issue with the request, such as invalid parameters, authentication failure, or insufficient permissions
• 5xx – Server ErrorIndicates a problem on the server side. These are typically temporary and may resolve if retried after some time.

Success Reponses

A successful API request will return an appropriate HTTP status code, and the response body will vary depending on the endpoint.

The following status codes indicate a successful request:

Failure Responses

When a request fails, AgentSync APIs return a structured error response to help developers identify and resolve issues quickly.

Standard Error Format

Most errors follow this standardized format:

{
  "timestamp": 1613510729601,
  "status": 500,
  "error": "Internal Server Error",
  "message": "Error message describing why this was an error.",
  "path": "/v2/{endpoint}"
}

⚠️ While this is the most common error format returned by the AgentSync API, there may be exceptions depending on the endpoint or specific error scenario.

Common AgentSync Errors & Troubleshooting

400 - Bad Request

This typically occurs due to invalid parameters or malformed requests.

{
  "timestamp": 1742929112,
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid parameter values provided - {parameter}:[{invalid values}]",
  "path": "{endpoint_path}"
}

How to troubleshoot:

• Double-check the parameter names and values in your request body or query string.
• Ensure all required fields are present and properly formatted.

401 - Unauthorized

Returned when the request is missing valid authentication credentials.

{
    "message": "Unauthorized"
}

How to troubleshoot:

• Confirm you're including the Authorization header with a valid Bearer token.
• If your token has expired, retrieve a new one using the client credentials flow.
• Ensure the correct client_id and client_secret are being used with the correct token URL.

404 - Not Found

This indicates that the requested resource could not be found.

{
  "timestamp": 1742929112,
  "status": 404,
  "error": "Not Found",
  "message": "Error message describing what was not found",
  "path": "{requested endpoint}"
}

How to troubleshoot:

• If querying by an NPN or external ID, confirm that the value is correct.
• Ensure the endpoint path is spelled correctly.

⚠️ Requests that return a 404 for a non-existent NPN will not be billed.

429 - Too Many Request

This error indicates you've exceeded the API rate limit.

{
  "messsage": "API rate limit exceeded"
}

How to troubleshoot:

• Reduce the frequency of your requests.
• Implement rate limiting or exponential backoff in your integration.
• If receiving on the token endpoint, be sure you are re-using your tokens
• If you need additional support, contact AgentSync support.

500 - Internal Server Error

An unexpected error occurred on AgentSync’s side. Please do not retry 500 requests.

{
  "timestamp": 1613510729601,
  "status": 500,
  "error": "Internal Server Error",
  "message": "Error message describing why this was a server error.",
  "path": "{requested endpoint}"
}

How to troubleshoot:

• Do NOT retry 500 errors immediately.
• These are usually transient issues and the AgentSync team is automatically alerted.
• If the issue persists, contact AgentSync support with the X-Trace-ID from the response headers.

Possible HTTP Error Status Codes