Error Handling

The format, the status codes, and the zero-knowledge guarantees that shape how errors are returned.

Endpoint schemas and parameter details live in the API Reference. This page covers error behavior — the format, the status codes, and the zero-knowledge guarantees that shape how errors are returned.

RFC 7807 Problem Details

All errors are returned as RFC 7807 Problem Details objects with Content-Type: application/problem+json.

Every error response includes these fields:

Field	Type	Description
`type`	string (URI)	Machine-readable error identifier. Always follows the pattern `https://api.kyndex.co/errors/{ERROR_CODE}`
`title`	string	Human-readable summary (e.g. "Bad Request", "Forbidden")
`status`	integer	HTTP status code
`code`	string	Machine-readable error code from the `ErrorCode` enum — use this for programmatic error handling
`instance`	string (opt)	The request path that triggered the error

Example:

{
  "type": "https://api.kyndex.co/errors/INVALID_REQUEST",
  "title": "Bad Request",
  "status": 400,
  "code": "INVALID_REQUEST",
  "instance": "/v1/documents"
}

Error Code Reference

The type URI always follows the pattern:

https://api.kyndex.co/errors/{ERROR_CODE}

400 Bad Request

Code	When	Recovery
`MISSING_PARAMETER`	A required parameter is absent from the request.	Check the endpoint documentation and include all required fields.
`INVALID_PARAMETER`	A parameter value is malformed or outside allowed bounds.	Validate the parameter format against the endpoint schema.
`INVALID_REQUEST`	Request body or query parameters failed schema validation.	Fix your request against the endpoint schema.
`VALIDATION_ERROR`	Request failed one or more validation rules (e.g. constraints, format).	Adjust the request to pass all validation rules.

401 Unauthorized

Code	When	Recovery
`UNAUTHORIZED`	Access token is missing, expired, or invalid.	Refresh via `/auth/tokens/refresh`. If refresh fails, re-authenticate from login.
`INVALID_TOKEN`	Session token failed cryptographic verification or is malformed.	Same as `UNAUTHORIZED` — refresh or re-authenticate.
`TOKEN_EXPIRED`	Access token has expired.	Refresh via `/auth/tokens/refresh`.
`SESSION_LOCKED`	Valid token, but session lacks `owner_token` / `user_member_token` — data access denied.	Pass `owner_token` and `user_member_token` in the next `/auth/tokens/refresh` call. See Session Lifecycle.

403 Forbidden

Code	When	Recovery
`FORBIDDEN`	Valid token, but insufficient permissions for this resource or action.	Check your role and membership. You may not have access to this resource.
`INSUFFICIENT_PERMISSIONS`	Operation requires elevated permissions you do not have.	Check the `code` field. You may need a different role or entity ownership.
`CSRF_REQUIRED`	`X-Kyndex-Request: 1` header is missing on a mutation request.	Add `X-Kyndex-Request: 1` to the request headers.

404 Not Found

Code	When	Recovery
`NOT_FOUND`	Route path does not match any endpoint (catch-all).	Check the URL path and HTTP method.
`USER_NOT_FOUND`	User ID does not exist or is not accessible.	Verify the user ID. On authenticated endpoints, returns `404` for both missing and inaccessible resources.
`DOCUMENT_NOT_FOUND`	Document ID does not exist or is not accessible.	Verify the document ID. On authenticated endpoints, returns `404` for both missing and inaccessible resources.
`GRANT_NOT_FOUND`	Grant ID does not exist or is not accessible.	Verify the grant ID. On authenticated endpoints, returns `404` for both missing and inaccessible resources.

409 Conflict

Code	When	Recovery
`CONFLICT`	Resource is in a conflicting state or operation violates a constraint.	Check the `code` field for the specific conflict.
`EMAIL_EXISTS`	Email address is already registered.	Use a different email or recover the existing account.
`GRANT_CLAIM_LIMIT_EXCEEDED`	Grant has been claimed the maximum number of times.	Create a new grant if you need additional claims.

413 Payload Too Large

Code	When	Recovery
`PAYLOAD_TOO_LARGE`	Document upload exceeds the 100 MB size limit.	Reduce file size before encrypting and uploading.

415 Unsupported Media Type

Code	When	Recovery
`UNSUPPORTED_MEDIA_TYPE`	`Content-Type` header is missing or not supported for this endpoint.	Use `application/json` for JSON requests or `application/octet-stream` for binary uploads.

429 Too Many Requests

Code	When	Recovery
`RATE_LIMITED`	Request rate limit exceeded.	Read the `Retry-After` response header. Back off exponentially. See Rate Limiting page.

500 Internal Server Error

Code	When	Recovery
`INTERNAL_ERROR`	Unexpected server error (catch-all).	Retry with exponential backoff. If the error persists, contact support.
`DATABASE_ERROR`	Database operation failed (connection, query, constraint).	Retry with exponential backoff. If persistent, contact support.
`KMS_ERROR`	Key management service call failed.	Retry with exponential backoff. If persistent, contact support.
`STORAGE_ERROR`	Object storage operation failed (upload, download, deletion).	Retry with exponential backoff. If persistent, contact support.
`VERIFICATION_FAILED`	Third-party identity verification service returned an error.	Retry with exponential backoff. If persistent, contact support.

503 Service Unavailable

Code	When	Recovery
`SERVICE_UNAVAILABLE`	A required upstream dependency is temporarily down.	Retry with exponential backoff. If persistent, contact support.

Anti-Oracle Guarantee: Why You See 404 For Both Cases

This is the most important behavioral difference from typical REST APIs.

Literal never reveals whether a resource exists. When you request a resource you cannot access, the server returns 404 Not Found with the message "not found or access denied" — regardless of whether the resource actually exists. Both missing resources and permission failures produce the same status code and the same response shape.

This is deliberate. In a zero-knowledge system, distinguishing "doesn't exist" from "you can't access it" is an information leak. An attacker could probe resource IDs to learn which documents, grants, or entities are real.

The guarantee: the server's response to GET /documents/{id} is identical whether {id} is a real document you can't access or a completely fabricated UUID.

This pattern extends beyond resource lookups:

OPRF challenge (POST /auth/challenges) — evaluates a blinded ristretto255 point without learning the input email. The server's response is indistinguishable regardless of whether the email is registered.
Grant discovery (GET /grants) — uses view tags that produce ~1/256 collisions, so the server cannot distinguish the intended recipient from noise.
Public key lookup (GET /users/{userId}/public-keys) — returns 404 only because the user ID namespace is random UUIDs with no sequential pattern to enumerate.

Status Code Summary

Status	When you'll see it	What to do
`400`	Request body or query params fail schema validation	Fix your request against the endpoint schema.
`401`	Token missing, expired, or revoked	Refresh via `/auth/tokens/refresh`. If that fails, re-authenticate.
`403`	Valid token, but insufficient permissions	Check your role and entity membership.
`404`	Resource not found or access denied on authenticated endpoints	Check the URL path and your authorization.
`409`	Duplicate resource or invalid state transition	Check the `code` field for the specific conflict.
`413`	Upload exceeds 100 MB	Reduce file size before encrypting.
`415`	Wrong or missing `Content-Type`	Use `application/json` or `application/octet-stream`.
`429`	Rate limit exceeded	Read `Retry-After` header. Back off.
`500`	Unexpected server error	Retry with exponential backoff. If persistent, contact support.
`503`	Upstream dependency temporarily unavailable	Retry with exponential backoff. If persistent, contact support.

On this page