Skip to main content
All errors follow a consistent structure: 
{
  "error": {
    "code": "invalid_identifier_type",
    "message": "The identifier type is not recognized.",
    "details": [
      {
        "field": "identifiers[0].type",
        "issue": "Must be one of: email, phone, username, ip, domain, name, url, address, company_name, social_url"
      }
    ]
  },
  "request_id": "req_01JNQBC4X8Y2Z3A"
}
Always include the request_id when contacting support. It links to the full request context on the Intrace side.

​
400 Bad Request

The request body is malformed or a required field is missing.
CodeCauseResolution
request_malformedThe request body is not valid JSON.Fix the JSON syntax.
field_requiredA required field is missing. details identifies the field.Add the missing field.
field_invalidA field value fails validation. details identifies the field and constraint.Correct the field value.

​
401 Unauthorized

The request did not include valid credentials.
CodeCauseResolution
credentials_missingNo Authorization header or X-API-Key header was provided.Include credentials in the request.
token_expiredThe Bearer JWT has expired.Obtain a new token from your IdP.
token_invalidThe Bearer JWT signature or claims are invalid.Check OIDC_ISSUER_URL and OIDC_AUDIENCE configuration.
api_key_invalidThe provided API key does not exist or has been revoked.Verify the key or request a new one from Intrace.

​
403 Forbidden

The authenticated principal does not have permission for the requested operation.
CodeCauseResolution
insufficient_scopeThe principal’s role does not grant access to this endpoint.Contact your administrator to review role assignments.

​
404 Not Found

CodeCauseResolution
not_foundThe requested resource (lookup result, connector, audit record) does not exist.Verify the ID. If querying a past result, it may have exceeded the result retention period.

​
422 Unprocessable Entity

The request is syntactically valid but cannot be processed as submitted.
CodeCauseResolution
invalid_identifier_typeThe type field of an identifier is not recognized.Use a supported identifier type.
identifier_format_invalidAn identifier value does not match the required format for its type (e.g. a phone number not in E.164 format).Reformat the identifier.
no_identifiersThe identifiers array is empty.Provide at least one identifier.
too_many_identifiersMore than 20 identifiers were submitted in a single request.Split into multiple requests.

​
429 Too Many Requests

The request rate limit has been exceeded.
CodeCauseResolution
rate_limit_exceededThe per-minute request limit for this principal has been reached.Wait for the duration indicated by the Retry-After response header before retrying.
Rate limit headers are included in all 429 responses:
HeaderDescription
Retry-AfterSeconds to wait before the next request will succeed.
X-RateLimit-LimitThe configured request limit per minute.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp when the current window resets.
See Rate Limits for limit values and configuration.

​
500 Internal Server Error

CodeCauseResolution
internal_errorAn unexpected error occurred in the engine.Retry the request. If the error persists, contact Intrace support with the request_id.
signing_failedThe engine could not sign the report.Check the SIGNING_PRIVATE_KEY_PATH configuration and key file permissions.
database_errorThe engine could not write to its database.Check database connectivity and disk space.