Skip to main content

Error Codes Reference

Complete list of error codes returned by L{CORE} services.

Attestor Errors​

HTTP Status Codes​

StatusMeaning
200Success
400Bad Request - Invalid parameters
401Unauthorized - Missing/invalid auth
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limited
500Internal Error - Server failure
502Bad Gateway - Provider failed
503Service Unavailable - Cartesi down

Error Response Format​

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable description",
    "details": {}
  }
}

Authentication Errors​

AUTH_MISSING​

Missing authorization header.

{
  "code": "AUTH_MISSING",
  "message": "Authorization header required"
}

Fix: Add Authorization: Bearer <token> header.

AUTH_INVALID​

Token is malformed or expired.

{
  "code": "AUTH_INVALID",
  "message": "Invalid or expired token"
}

Fix: Refresh token or re-authenticate.

AUTH_INSUFFICIENT​

Token lacks required permissions.

{
  "code": "AUTH_INSUFFICIENT",
  "message": "Token does not have required permissions"
}

Fix: Use admin token for admin operations.

Request Errors​

INVALID_REQUEST​

Request body malformed or missing required fields.

{
  "code": "INVALID_REQUEST",
  "message": "Invalid request body",
  "details": {
    "field": "provider",
    "issue": "required"
  }
}

Fix: Check request body format against API docs.

INVALID_PARAMETER​

Parameter value is invalid.

{
  "code": "INVALID_PARAMETER",
  "message": "Invalid parameter value",
  "details": {
    "parameter": "address",
    "value": "not-an-address",
    "expected": "Ethereum address (0x...)"
  }
}

Fix: Use correct parameter format.

SCHEMA_NOT_FOUND​

Requested provider schema doesn't exist.

{
  "code": "SCHEMA_NOT_FOUND",
  "message": "Provider schema not found",
  "details": {
    "schema_id": "unknown-schema"
  }
}

Fix: Use GET /api/lcore/schemas to list available schemas.

ATTESTATION_NOT_FOUND​

Requested attestation doesn't exist.

{
  "code": "ATTESTATION_NOT_FOUND",
  "message": "Attestation not found",
  "details": {
    "claim_id": "claim-xyz"
  }
}

Fix: Verify claim ID is correct.

Provider Errors​

PROVIDER_UNAVAILABLE​

External data provider is not responding.

{
  "code": "PROVIDER_UNAVAILABLE",
  "message": "Provider service unavailable",
  "details": {
    "provider": "http",
    "url": "https://api.example.com",
    "error": "Connection timeout"
  }
}

Fix: Check provider URL is correct and accessible.

PROVIDER_AUTH_FAILED​

Authentication with provider failed.

{
  "code": "PROVIDER_AUTH_FAILED",
  "message": "Provider authentication failed",
  "details": {
    "provider": "http",
    "status": 401
  }
}

Fix: Verify provider credentials/tokens.

PROVIDER_INVALID_RESPONSE​

Provider returned unexpected response format.

{
  "code": "PROVIDER_INVALID_RESPONSE",
  "message": "Invalid response from provider",
  "details": {
    "expected": "JSON object",
    "received": "HTML"
  }
}

Fix: Check provider endpoint returns expected format.

ZKTLS_PROOF_FAILED​

Failed to generate zkTLS proof.

{
  "code": "ZKTLS_PROOF_FAILED",
  "message": "zkTLS proof generation failed",
  "details": {
    "reason": "TLS version not supported"
  }
}

Fix: Ensure target uses TLS 1.2+.

Encryption Errors​

ENCRYPTION_KEY_MISSING​

Encryption key not configured.

{
  "code": "ENCRYPTION_KEY_MISSING",
  "message": "Encryption key not registered"
}

Fix: Register encryption key via POST /api/lcore/encryption-key.

DECRYPTION_FAILED​

Unable to decrypt data.

{
  "code": "DECRYPTION_FAILED",
  "message": "Failed to decrypt data",
  "details": {
    "reason": "Invalid private key"
  }
}

Fix: Verify correct private key is being used.

INVALID_KEY_FORMAT​

Key is not in expected format.

{
  "code": "INVALID_KEY_FORMAT",
  "message": "Invalid key format",
  "details": {
    "expected": "base64-encoded NaCl public key",
    "received": "hex string"
  }
}

Fix: Use base64-encoded NaCl keys.

Access Control Errors​

NO_GRANT_FOUND​

No access grant exists for requester.

{
  "code": "NO_GRANT_FOUND",
  "message": "No access grant found",
  "details": {
    "owner": "0x1234...",
    "requester": "0x5678..."
  }
}

Fix: Request access grant from data owner.

GRANT_EXPIRED​

Access grant has expired.

{
  "code": "GRANT_EXPIRED",
  "message": "Access grant has expired",
  "details": {
    "grant_id": "grant-123",
    "expired_at": 1704067200
  }
}

Fix: Request new access grant from owner.

NOT_OWNER​

Caller is not the data owner.

{
  "code": "NOT_OWNER",
  "message": "Only data owner can perform this action"
}

Fix: Sign request with owner's wallet.

Cartesi Errors​

CARTESI_UNAVAILABLE​

Cartesi node is not responding.

{
  "code": "CARTESI_UNAVAILABLE",
  "message": "Cartesi node unavailable",
  "details": {
    "url": "http://localhost:10000",
    "error": "Connection refused"
  }
}

Fix:

  1. Check Cartesi node is running
  2. Verify CARTESI_HTTP_ADDRESS=0.0.0.0 is set
  3. Check firewall allows port 10000

CARTESI_REJECTED​

Cartesi rejected the input.

{
  "code": "CARTESI_REJECTED",
  "message": "Input rejected by Cartesi",
  "details": {
    "reason": "Invalid payload format"
  }
}

Fix: Check payload format matches Cartesi handler expectations.

INPUTBOX_TX_FAILED​

Failed to submit transaction to InputBox.

{
  "code": "INPUTBOX_TX_FAILED",
  "message": "InputBox transaction failed",
  "details": {
    "reason": "Insufficient gas",
    "wallet": "0x..."
  }
}

Fix: Fund wallet with ETH for gas.

Blockchain Errors​

RPC_UNAVAILABLE​

Blockchain RPC endpoint not responding.

{
  "code": "RPC_UNAVAILABLE",
  "message": "Blockchain RPC unavailable",
  "details": {
    "url": "https://arb-sepolia.g.alchemy.com/..."
  }
}

Fix: Check RPC URL and API key.

INSUFFICIENT_FUNDS​

Wallet lacks funds for gas.

{
  "code": "INSUFFICIENT_FUNDS",
  "message": "Insufficient funds for gas",
  "details": {
    "wallet": "0x...",
    "balance": "0.001",
    "required": "0.01"
  }
}

Fix: Fund wallet at https://sepoliafaucet.com

NONCE_TOO_LOW​

Transaction nonce conflict.

{
  "code": "NONCE_TOO_LOW",
  "message": "Nonce too low",
  "details": {
    "expected": 42,
    "received": 40
  }
}

Fix: Wait for pending transactions or reset nonce.

Rate Limit Errors​

RATE_LIMITED​

Too many requests.

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "details": {
    "limit": 10,
    "window": "60s",
    "retry_after": 45
  }
}

Fix: Wait for retry_after seconds before retrying.

Debugging Tips​

Check Logs​

# Attestor logs
docker-compose logs attestor

# Cartesi logs
docker-compose logs cartesi

Test Connectivity​

# Test Attestor
curl http://localhost:8001/healthcheck

# Test Cartesi
curl "http://localhost:10000/inspect/$(python3 -c "import urllib.parse; print(urllib.parse.quote('{\"type\":\"health\",\"params\":{}}'))")"

Verify Configuration​

# Check environment
echo $LCORE_ENABLED
echo $LCORE_NODE_URL
echo $LCORE_DAPP_ADDRESS