API Error Reference

Developer

When interacting with the DataCentral REST API, you may encounter errors. DataCentral uses standard HTTP status codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with DataCentral's servers.

---

1. Standard Error Format

When an API request fails, DataCentral returns a JSON response containing an error object with more details to help you debug the issue.

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "reportId is required",
    "details": {
      "field": "reportId"
    }
  }
}

• success: Always false for error responses.
• code: A short, machine-readable string identifying the type of error.
• message: A human-readable description of the error.
• details: (Optional) Additional context, such as the specific field that failed validation.

2. Common Error Codes

The following table lists the most common error code strings returned by the API:

Error Code	HTTP Status	Description	Troubleshooting
invalid_request	400 Bad Request	The request was malformed or missing required parameters.	Check the details.field in the response to see which parameter was missing or invalid.
unauthorized	401 Unauthorized	The API key or Bearer token is missing, expired, or invalid.	Ensure you are passing a valid token in the Authorization header.
forbidden	403 Forbidden	You are authenticated, but your role does not grant permission to perform this action.	Verify that the user or service account has the correct administrative or report roles.
not_found	404 Not Found	The requested resource (e.g., a user, report, or task) does not exist.	Verify the ID of the resource in your request URL.
conflict	409 Conflict	The request conflicts with the current state of the server (e.g., trying to create a user with an email that already exists).	Check if the resource already exists before attempting to create it.
rate_limited	429 Too Many Requests	You have exceeded the API rate limit.	Implement exponential backoff in your application and retry the request later.
internal_error	500 Internal Server Error	An unexpected error occurred on the DataCentral servers.	If this persists, contact DataCentral Support with the timestamp and request details.

3. Webhook Error Handling

If you are using Action Tasks to send data from DataCentral to your external webhook endpoints, DataCentral expects your server to return a 2xx success code.

If your webhook endpoint returns a 4xx or 5xx error, or if the request times out:

1. The user who triggered the Action Task in the report will see an error notification.
2. The failure will be logged in the DataCentral Audit Log, including the HTTP status code returned by your server.

DataCentral does not automatically retry failed Action Task webhooks. Your application should be designed to handle potential data loss if an endpoint is temporarily unavailable.