Errors

Error Responses

The Integration API returns standard HTTP status codes. Requests use the IntegrationApiKey scheme with the X-Survanta-Api-Key header. Authentication and scope-authorization failures use the shared BaseResponse JSON envelope with errorCode, errorMessage, and data fields.

Error Response Format

Missing, blank, invalid, and unknown API keys return HTTP 401 with this exact response:

{
  "errorCode": 401,
  "errorMessage": "Authentication is required. Provide valid credentials or a valid API key.",
  "data": null
}

An authenticated key that lacks the endpoint's required scope returns HTTP 403 with this exact response:

{
  "errorCode": 403,
  "errorMessage": "You do not have permission to access this resource.",
  "data": null
}

These exact envelopes apply to the 401 and 403 cases above. Framework query-binding failures can still use ASP.NET Core validation problem details.

Status Codes

400 Bad Request

The request is malformed or contains invalid parameter values.

The current read actions have no body model. Raw-response page/pageSize values are normalized and clamped rather than rejected. A 400 can still come from framework route/query binding for malformed values.

Action: Correct the request parameters before retrying.

401 Unauthorized

The API key is missing, blank, invalid, or unknown, or authentication rejected the client. Rejection includes inactive, revoked, or expired clients; an inactive tenant; blocked subscription access; zero or exceeded External integrations; missing Report API access for ReportsRead or UsageRead; and missing Raw response API access for RawResponsesRead. These failures occur during authentication and therefore return 401, not 403.

Common causes:

• The X-Survanta-Api-Key header was not included in the request.
• The key value is incorrect or was truncated during copy-paste.
• The integration client was revoked by an authorized administrator.
• The key was rotated and the old key value is still being used.

Action: Verify the key is included in the X-Survanta-Api-Key header with its full value. If the key was rotated or revoked, update the consuming system with the new key.

403 Forbidden

The API key is valid but the client does not have the scope required by the requested endpoint.

Common causes:

• Calling metadata, survey-report, or response-summary endpoints without ReportsRead.
• Calling the usage endpoint without UsageRead.
• Calling the raw-responses or response-file endpoint without RawResponsesRead.

Action: Use another client that already has the required scope, or ask an authorized administrator to create a replacement client with that scope and update the consuming system. The current dashboard does not expose scope editing for an existing client.

404 Not Found

The current list/report actions normally return empty arrays rather than 404. The integration file endpoint returns 404 when it cannot resolve a current, non-deleted answer-file association authorized for the key's tenant.

Action: Re-read current raw-response file descriptors and use only their current answerFileId values. Deleted and cross-tenant associations are intentionally unavailable; the file pipeline also requires active file metadata.

429 Too Many Requests

The request was rejected by a configured Integration API rate limiter.

The endpoint is protected by named rate-limit policies. Honor Retry-After when the configured limiter includes it; do not require that header unless verified in the deployment:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Action: Implement exponential backoff, respect Retry-After when present, and avoid high-frequency polling.

500 Internal Server Error

An unexpected server-side error occurred.

Action: Retry after a short delay. If the error persists, report the request timestamp and any correlation information actually returned by the deployment; a traceId is not guaranteed by these controllers.

Idempotency Note

Integration endpoints do not mutate survey/report data, but every successfully authenticated request updates the client's LastUsedAt and appends an ApiCall audit row before scope enforcement. Retries are data-read safe but are not operationally side-effect-free.