Reference

API Errors and Status Codes

This page documents the HTTP status codes and error response shapes returned by the Liccium APIs. Use this reference to handle errors consistently in your client.

Declaration API

Success

Code	Description
200	Declaration accepted successfully. Response includes rayId, message, env, iscc, cidV1, version.

Client Errors

Code	Description	Response shape
400	Bad Request – Invalid ISCC, timestamp validation failed, signature verification failed, or TSA verification failed.	ErrorResponse: error, message, optional iscc, jwkError, tsaErrors, providedTimestamp, serverTime.
401	Unauthorized – Invalid or missing API key.	ErrorResponse: error, message.
405	Method Not Allowed – Only POST is accepted.	ErrorResponse: error, message.
422	Unprocessable Entity – Declaration validation failed (schema, structure, or business rules).	ValidationErrorResponse: error, message, validationErrors (array of strings), optional schemaUrl, contextUrl, iscc.

Server Errors

Code	Description	Response shape
500	Internal Server Error – Failed to process the declaration.	message, rayId.
502	Bad Gateway – Failed to fetch or process schema/context.	error, message, optional schemaUrl, contextUrl, iscc.

ErrorResponse schema

Code
 
{
  "error": "string (error type or title)",
  "message": "string (detailed message)",
  "iscc": "string (optional)",
  "jwkError": "string (optional)",
  "tsaErrors": ["string"] (optional),
  "providedTimestamp": 1736251200000,
  "serverTime": 1736251320000
}

ValidationErrorResponse schema

Code
 
{
  "error": "Declaration validation failed",
  "message": "Summary of the validation failure",
  "schemaUrl": "https://...",
  "contextUrl": "https://...",
  "validationErrors": [
    "publicMetadata.iscc: invalid ISCC format",
    "publicMetadata.timestamp: required property missing"
  ],
  "iscc": "ISCC:INVALID"
}

Example 400 responses

Invalid ISCC:

Code
 
{ "error": "Invalid ISCC code: ISCC:INVALID" }

Timestamp validation failed:

Code
 
{
  "error": "Timestamp validation failed",
  "message": "Timestamp outside allowed window",
  "providedTimestamp": 1736251200000,
  "serverTime": 1736251320000,
  "iscc": "ISCC:KEC2EHPLVKPVDFVORULRVCUFXL3DZ4SA6JSDQLNOXEVYYCXR4N5IBDY"
}

Signature verification failed:

Code
 
{
  "error": "Signature verification failed",
  "message": "Invalid signature",
  "jwkError": "invalid signature"
}

TSA signature verification failed:

Code
 
{
  "error": "TSA signature verification failed",
  "message": "TSA content verification failed",
  "tsaErrors": ["Hash mismatch - the timestamp is not for the provided signature data"],
  "iscc": "ISCC:KEC2EHPLVKPVDFVORULRVCUFXL3DZ4SA6JSDQLNOXEVYYCXR4N5IBDY"
}

Example 422 responses

Schema validation failed:

Code
 
{
  "error": "Declaration validation failed",
  "message": "publicMetadata does not conform to schema",
  "validationErrors": [
    "publicMetadata.iscc: invalid ISCC format",
    "publicMetadata.timestamp: required property missing"
  ],
  "iscc": "ISCC:INVALID"
}

Structure validation failed:

Code
 
{
  "error": "Declaration structure validation failed",
  "message": "Required structure not met",
  "validationErrors": [
    "signature: required",
    "tsaSignature: required",
    "declarationMetadata.publicMetadata.iscc: required"
  ]
}

Metadata and Search APIs

• 401 – Unauthorized (invalid or missing API key). Same ErrorResponse shape.
• 404 – Not Found (e.g. CID not found). ErrorResponse: error, message.
• 410 – Gone. The declaration behind this CID was fully deleted. The body is the public deletion marker (cid, iscc, status: "deleted", deletedAt, authorizedBy, chain links) and the header x-declaration-status: deleted is set. Unlike a 404, the CID did exist. See Redaction & Deletion.
• 500 – Internal Server Error. ErrorResponse or message, rayId.

Successful metadata responses carry the header x-declaration-status with active, redacted or deleted. A redacted declaration is still returned in full; the header is the only signal. Inside a provenance chain, the Search API flags redacted members with metaInternal.redacted: true and deleted members with metaInternal.deleted: true plus their deletionMarker.

Redaction and Deletion API

Routes: POST /v1/redact, GET /v1/redact/jobs/{jobId}, POST /v1/delete, GET /v1/redaction/status/{cid}, and the administrator routes GET /v1/redacted and GET /v1/redaction/stats. Full reference: Redaction API.

Code	Description
200	Done, or the declaration already was in the requested state ("changed": false).
202	Batch redaction accepted; the body carries jobId and statusPath to poll.
207	Recursive deletion finished with partial failures; per-CID results in the body.
400	Invalid body, an ISCC instead of a CID, more than 500 CIDs, or a batch sent to /v1/delete.
401	Missing or invalid API key.
403	The key is not bound to the declarer of this declaration, deletion is not enabled for it, or recursive was sent without the administrator role.
404	Unknown CID or job.
410	The declaration was fully deleted; deletion is terminal, so it can no longer be redacted or un-redacted.

Error bodies use the ErrorResponse shape with an additional machine-readable code (invalid_cid, forbidden, not_found, deleted).

Best practices

See also

• Declaration API – Full request/response and examples
• Redaction & Deletion – Redaction, full deletion and the signals verifying parties receive
• General Information – Metadata structure and validation
• Metadata Signature – Signing and validation requirements