Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt

Use this file to discover all available pages before exploring further.

Canonical error codes and verdicts used across the Truthlocks platform. These codes are stable and can be used for programmatic error handling.

​
Verification Verdicts

VerdictCLI ExitDescription
VALID0Attestation verified successfully
ALTERED10Payload hash does not match
REVOKED11Attestation has been revoked
KEY_COMPROMISED12Signing key marked as compromised
KEY_EXPIRED13Signing key has expired
LOG_PROOF_FAILED14Transparency log proof verification failed
SIGNATURE_INVALID15Cryptographic signature verification failed

​
Verification reasons

When you call the Verify endpoint, the response includes a reasons array with additional context. These reason codes are informational and appear alongside the verdict:
ReasonVerdictDescription
document_hash_mismatchALTEREDThe document_hash_hex you provided does not match the hash stored at mint time
document_hash_not_stored(any)The attestation was minted without a document hash, so the document hash check was skipped

​
API error codes

​
General

CodeHTTPDescription
INVALID_INPUT400Request validation failed
INVALID_REQUEST400Request body or parameters are malformed
INVALID_ID400Identifier is not a valid UUID
NOT_FOUND404Resource not found
UNAUTHORIZED401Authentication required
FORBIDDEN403Permission denied
CONFLICT409Resource state conflict
INTERNAL_ERROR500An unexpected server error occurred
DB_ERROR500A database operation failed

​
Attestations and issuers

CodeHTTPDescription
ISSUER_NOT_TRUSTED403Issuer must be in trusted status to mint attestations
KEY_INACTIVE400Signing key is not active

​
API keys

CodeHTTPDescription
NAME_REQUIRED400A key name is required
KEY_ID_REQUIRED400Key ID parameter is missing
KEY_NOT_FOUND404API key not found
KEY_LIMIT409Maximum number of active API keys reached (5 per consumer)

​
Consumer

CodeHTTPDescription
CONSUMER_REQUIRED400A consumer email reference is required

​
Identity and DID

CodeHTTPDescription
MISSING_DID400DID parameter is required
DID_NOT_FOUND404DID not found or the associated issuer has been revoked
MISSING_ID400Issuer ID parameter is required
EMAIL_NOT_VERIFIED403Email address has not been verified

​
SSO

CodeHTTPDescription
DISCOVERY_FAILED400OIDC discovery configuration could not be loaded
METADATA_FETCH_FAILED400SAML IdP metadata could not be fetched
CRYPTO_ERROR500An encryption operation failed
TEST_FAILED400SSO connection test did not succeed
AUTH_FAILED401SSO authentication failed
INVALID_STATE401OAuth or SAML state parameter is invalid
EXPIRED_SESSION401SSO login session has expired
REPLAY_DETECTED401OAuth or SAML state token has already been used
CONFIG_ERROR500SSO configuration is missing or invalid

​
Policy and governance

CodeHTTPDescription
POLICY_VIOLATION403Request violates an active policy

​
Billing and limits

CodeHTTPDescription
BILLING_LIMIT402Billing quota exhausted for the current cycle
LIMIT_REACHED429Monthly protection limit reached
SEAT_LIMIT402Team seat limit reached — upgrade your plan or remove an existing member

​
Data residency

CodeHTTPDescription
REGION_MISMATCH409Tenant is pinned to a different region than the one processing the request

​
Retryable vs. terminal errors

When deciding whether to retry a failed request, use the HTTP status code to determine if the error is transient or permanent.

​
Retryable (transient)

These errors are automatically retried by the SDKs when MaxRetries (or equivalent) is configured:
HTTP statusCodeWhen to retry
408Request TimeoutImmediately — the server did not receive the request in time
429RATE_LIMITEDAfter the duration specified in the Retry-After header
500INTERNAL_ERRORWith exponential backoff — transient server issue
502Bad GatewayWith exponential backoff — upstream service unavailable
503Service UnavailableWith exponential backoff — service temporarily overloaded
504Gateway TimeoutWith exponential backoff — upstream service timed out

​
Terminal (do not retry)

These errors indicate a problem with the request that won’t resolve by retrying:
HTTP statusExample codesAction
400INVALID_INPUT, INVALID_REQUESTFix the request payload
401UNAUTHORIZEDCheck your API key or authentication token
403FORBIDDEN, ISSUER_NOT_TRUSTED, POLICY_VIOLATIONCheck permissions or issuer status
404NOT_FOUNDVerify the resource ID exists
409CONFLICTResolve the state conflict before retrying
All three SDKs handle retryable errors automatically with exponential backoff and jitter. You only need manual retry logic if you’ve disabled automatic retries or want custom behavior on top of the SDK defaults.

​
Error response format

Every error response returns a JSON object with two fields: 
{
  "code": "ISSUER_NOT_TRUSTED",
  "message": "Issuer must be in trusted status to mint attestations"
}
  • code — a stable, machine-readable error code from the tables above. Use this for programmatic error handling.
  • message — a human-readable description of what went wrong. Messages may change between releases; do not match on them programmatically.
Error messages that would expose infrastructure details (such as database connection strings or internal hostnames) are automatically replaced with a generic message before being returned to the client. The original details are logged server-side only.

​
Gateway errors (RFC 7807)

When a request reaches the API gateway but does not match any valid route, the gateway returns a structured error response following the RFC 7807 Problem Details specification. This applies to 404 Not Found and 405 Method Not Allowed errors at the gateway level.

​
Response format

Gateway errors use application/problem+json as the content type and include four fields: 
{
  "type": "https://docs.truthlocks.com/ops/errors",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested path does not match any API route."
}
FieldDescription
typeA URI reference that identifies the error type. Points to this documentation page.
titleA short summary of the error. Either Not Found or Method Not Allowed.
statusThe HTTP status code — 404 or 405.
detailA human-readable explanation of the specific error.

​
When you see these errors

  • 404 Not Found — The request path does not match any API route. Double-check the URL, including the /v1/ version prefix and resource name.
  • 405 Method Not Allowed — The request path exists, but the HTTP method you used (for example, DELETE on a read-only endpoint) is not supported. Check the API reference for the correct method.

​
Handling gateway errors in code

If you parse error responses programmatically, check the Content-Type header to distinguish gateway errors from application errors:
  • application/problem+json — Gateway-level error (RFC 7807). Use the status and title fields.
  • application/json — Application-level error. Use the code and message fields.
const res = await fetch("https://api.truthlocks.com/v1/nonexistent");
const contentType = res.headers.get("content-type");

if (contentType?.includes("application/problem+json")) {
  // Gateway error — RFC 7807 format
  const problem = await res.json();
  console.error(`${problem.status} ${problem.title}: ${problem.detail}`);
} else {
  // Application error — standard format
  const error = await res.json();
  console.error(`${error.code}: ${error.message}`);
}
The Truthlocks SDKs handle both error formats automatically. You only need to distinguish between them if you are calling the API directly.

​
Canonical Enums

Algorithm

* Ed25519 * P-256 * P-384

Issuer Status

  • pending * trusted * suspended * revoked

Trust Tier

  • self_issued * verified_org * regulated_issuer

Key Status

  • ACTIVE * DISABLED * EXPIRED * COMPROMISED

Attestation Status

* ACTIVE * REVOKED * SUPERSEDED

Risk Rating

  • unknown * low * medium * high * critical