Skip to content

Invalid Input

URI: https://docs.ankatech.co/errors/invalid-input
HTTP Status: 400 Bad Request

When you see this

You sent a syntactically valid HTTP request, but one or more required fields are missing, empty, malformed, or conflicting. The server cannot proceed until you correct your payload.

Common Causes

  • Missing mandatory JSON properties
    – A required field like kid, kty, alg, or newKey was blank or not present.

  • Conflicting parameters
    – sourceKid names a key other than the one the token's header names, or neither names one. For a token addressed to or signed by several keys, sourceKid or recipientKid is absent or names no recipient or signer of the token, or newKid names an entry the operation keeps. The detail names the member and no key.

  • Malformed Base64 payload
    – A field expected to be Base64 (e.g. publicKey, p12FileBase64) failed to decode.

  • Invalid JSON structure
    – Your request body wasn’t well-formed or was missing the expected object schema.

  • Malformed JWE/JWS header
    – A detached JWE/JWS was missing required header elements (e.g. protected, iv, tag, or kid).

  • A decryptionKid that names none of the recipients of a PKCS#7 conversion
    – You submitted an EnvelopedData or SignedAndEnvelopedData structure to POST /api/v3/migration/convert-pkcs7-to-jose or its streaming twin with a decryptionKid whose certificate matches none of the file's recipients. decryptionKid is optional — when it is absent, the first recipient in encoded order whose tenant key admits decryption and encryption decrypts — but when it is present it must name one of them. This is invalid-input, not invalid-pkcs7: the file is a perfectly valid PKCS#7 structure — the request is what is inconsistent. Run POST /api/v3/migration/analyze-pkcs7 to list the recipients, then omit decryptionKid or supply a matching one.

  • An X25519 or X448 public key of low order
    – An ephemeral key in a JWE recipient's epk, or a public key you import (a JSON key, a composite component, or a PKCS#12 certificate or key entry), whose u-coordinate is 0, 1 or a point of small order. Such a key yields no usable shared secret (RFC 7748 §6.1), so it is refused on the crypto routes, both planes, and on key import.

  • A composite algorithm pairing the catalogue does not know
    – Creating, rotating to or importing a composite key whose pairing is not a catalogue entry. This is not a policy decision, so it carries no algorithm or refusedBy member, whatever the tenant's algorithm policy. An algorithm the catalogue knows but the algorithm policy in force does not admit is a different type, Algorithm Not Admitted.

  • A PKCS#7 serialization outside AUTO, COMPACT and JSON
    – The value is exact case; json, Compact or any other JOSE serialization name is refused, naming serialization, before the file is decoded or read.

  • A member a PKCS#7 request body does not define
    – Every PKCS#7 body — analyze and convert, compact and streaming (metadata part), at its root and inside algorithmPolicy — refuses a member it does not define, with a detail naming the member and never its value: Unsupported member 'validateCertificates' in the request body. Members the requests do not define — validateCertificates, validateTimestamp, algorithmPolicy.contentEncryptionUpgrade, and decryptionKid on analyze — are refused this way.

  • A certificate that does not match the PKCS#7 recipient
    – The decryptionKid resolves to a key whose certificate is not the one the message was encrypted to. An unresolvable decryptionKid is a 404 instead; this 400 means it resolved and did not match.

  • A licence import body that is not one JSON object
    – On POST /api/v3/admin/platform/license/import, the body was not a JSON object (an array, a scalar, trailing content, or not JSON at all): The request body must be a JSON object: the signed license artifact. The Admin API refuses it before the licence server is called, and no audit event is written. A JSON object that is not a valid licence artifact reaches the licence server and is refused there as License Artifact Invalid.

  • A usage-statement period or supersedes that is not well-formed
    – On POST /api/v3/admin/usage/statements, the calendar month or the statementId a correction supersedes was malformed. No statement is issued and no upstream call is made. A well-formed request the licence server will not answer — a month that is not yet final, or a second original for a month already stated — is a 409 instead, and names the correction path.

  • A usage-telemetry range, grain or page that is not well-formed
    – On GET /api/v3/admin/usage/telemetry, GET /api/v3/admin/platform/usage/telemetry and POST /api/v3/admin/usage/exports: from or to absent, a range whose from is later than its to, a grain other than day or month, or on the two reads a page outside 0..366 or a size outside 1..200. No upstream call is made and no export job is created. Unlike the licence server's own usage read above, an inverted range here is this type, not Invalid Date Range, which these three operations reserve for a span beyond the grain's cap.

  • A page request outside a paginated Admin API list's bounds
    – On the ten paginated entity lists of the Admin API (keys, actors, applications, capability grants, constraint policies, exchange contexts, credentials, internal crypto use cases, cross-tenant pending activations and Cryptographic Exchanges): a size above the list's cap (200; 50 on GET /api/v3/admin/exchanges), a size below 1 or a negative page where the list binds them itself, or a sort field outside the list's allow-list. Nothing is read. A sort refusal names the allow-list in detail — Sort field is not in the allow-list. Allowed: createdAt, name, status — and never repeats the field you sent. Each list's allow-list is published on its 400 response in the API reference.

Response Example

{
  "type": "https://docs.ankatech.co/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "Field 'algorithm' is required and must be one of the catalog values.",
  "instance": "/api/v3/admin/tenants/2f1c9d84-6b2e-4d3a-9f57-0a1b2c3d4e5f/keys",
  "timestamp": 1751500800,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.

The example above is an Admin API body, where the correlation identity is extensions.requestId; the Core API and the PQC Handshake API instead emit a top-level correlationId. Read the member your service emits — see Error Index & Overview.

The title is the answering service's: the Audit API answers every invalid-input refusal with the title Bad Request, on every plane. Two refusals carry a fixed detail: a body the PQC Handshake API cannot read as JSON (The request body is missing or is not a valid JSON document.) and an OpenAPI document key the API documentation hub does not know (The requested OpenAPI document key is not recognized.).

detail is always a single human-readable sentence. It is never a nested JSON document, even when the rejection originated in an internal upstream service: see S2S Relay Envelope for how a relayed rejection is composed.

How to Resolve

  1. Inspect the response detail: it will pinpoint exactly which field or constraint failed.
  2. Supply all required fields: make sure kid, kty, alg, etc. are non-empty strings.
  3. Resolve conflicting parameters: send sourceKid only when it equals the header's kid, when the header names none, or to name the ONE entry replaced in a token with several; send recipientKid to name the recipient that decrypts a JWE addressed to several keys.
  4. Validate Base64: ensure any Base64-encoded input (keys, JWE headers, PKCS#12) is correctly padded and valid.
  5. Check JWE/JWS structure: confirm your JSON Web Encryption/Signature includes all required fields (protected, iv, tag, kid).
  6. Use correct key types & operations: refer to the API reference for allowed combinations (encrypt, decrypt, sign, verify).
  7. Re-submit your request.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.