Responses and Errors

The API returns JSON. Use the HTTP status to determine whether the request succeeded and the response body for the result or error details.

Successful responses

Resource endpoints use a success envelope. List requests return an array in data; detail and write requests return an object as documented by the endpoint.

{
  "success": true,
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Example project"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1
  }
}

Field	Meaning
success	true for a successful request
data	The endpoint's response data; see its response-field table for the schema
meta	Pagination or other response metadata, where provided; it may be empty or omitted

For paginated lists, meta.total is the number of matching records, not the number on the current page. A successful query with no matching records returns an empty array. See Querying for pagination.

Summary endpoints use a different contract: meta.total counts the groups returned after applying the group limit. It is not the total number of source records or all possible groups. Check the summary endpoint’s aggregation rules before using it for a report.

Do not assume every resource has the same fields or that every nested value is populated. Handle documented null values and empty arrays, and ignore additional fields your integration does not use.

Error responses

Open API errors use a machine-readable code and a descriptive message:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Branch on the HTTP status and error.code. Use error.message for diagnostics rather than matching its exact wording.

HTTP status	Code	Meaning and action
400	BAD_REQUEST	Invalid parameters, body or resource state. Check the endpoint's requirements before retrying
401	UNAUTHORIZED	Missing, invalid, expired or revoked credentials. Check Authentication
403	FORBIDDEN	Scope, tenant access, key-owner permissions, environment or IP restrictions prevent the operation
403	HTTPS_REQUIRED	Call the API using HTTPS
403	FEATURE_NOT_ENABLED	The requested feature is not available for the company; check the endpoint's feature requirements
404	NOT_FOUND	The resource does not exist or is not available within the caller's access
405	METHOD_NOT_ALLOWED	The HTTP method is not supported for the requested path
409	WORKER_MATCH_REQUIRES_REVIEW	Worker creation found a possible existing worker; review the match in Requidex before proceeding
413	PAYLOAD_TOO_LARGE	The JSON body exceeds 50 MB; see File Uploads
429	RATE_LIMITED	The per-minute quota is exhausted; wait before retrying
429	DAILY_RATE_LIMITED	The daily quota is exhausted; see Rate Limits
500	INTERNAL_ERROR	An unexpected server error occurred; retry read requests with bounded backoff

Endpoint references list their specific validation and access requirements. A 404 must not be used to infer that a record exists outside your access.

Unknown paths and non-JSON responses

An unrecognised URL can return a generic 404 response instead of the Open API error envelope:

{
  "code": 404,
  "message": "Not found"
}

Check the base URL, path and HTTP method. Clients should also handle an empty or non-JSON response from a network intermediary without treating it as a successful API result.

Retries and troubleshooting

Retry transient network failures and server errors with a bounded delay and backoff. For 429, follow Rate Limits. Do not automatically retry a write after a timeout: the operation may have succeeded even if you did not receive its response. Check the record's current state and the endpoint's retry behaviour first.

For support, retain the HTTP method, path, UTC timestamp, status, error code and x-request-id response header. Include the key name or prefix when available. Remove credentials, personal data and temporary file URLs from logs and support messages.