FIND THE
FAILURE.
FIX THE CALL.

HTTP ERRORS

These failures stop the request before a normal verification result is returned. The body shapes below are stable; use the action in the last column to recover.

// 401 — no credential was received
{ "error": "API key required" }

// 429 — wait for the Retry-After duration
{
  "error": "rate_limited",
  "plan_id": "beta",
  "rpm": 60,
  "retry_after_seconds": 12
}

VERIFICATION ANOMALIES

Receive/pay verification failures are normally semantic 200 responses. Fix the request or the underlying invoice/payment data, inspect the next verification.verified value, and only proceed when it is true.

THREE-WAY MATCH

With "mode": "three_way_match", Truss checks the supplied PO, invoice, and receipt for amount, vendor_name, and date. The PO also needs po_number. Missing or incomplete documents produce verdict: "missing"; complete documents can produce verified, partial, or mismatch depending on how many comparisons match.

// 200 OK — semantic result, not an HTTP failure
{
  "authenticated": true,
  "owner_label": "your-key-label",
  "verification": {
    "mode": "three_way_match",
    "verdict": "missing",
    "verified": false,
    "missing_documents": ["receipt"],
    "comparisons": [],
    "matched_fields": [],
    "anomalies": [
      {
        "field": "documents.receipt",
        "severity": "error",
        "message": "receipt missing required fields (amount, vendor_name, date)"
      }
    ],
    "checked_at": "2026-08-29T12:00:00.000Z"
  }
}

Revoked and invalid supplied keys

A request with a revoked API key fails before verification with HTTP 401. Its exact JSON response is { "error": "Invalid or revoked API key" }. The response contains only the error field — never authenticated, verification, invocation_id, or other invocation fields.

curl -i -X POST https://api.truss.polsia.app/api/agents \
  -H "Authorization: Bearer truss_<revoked-or-invalid-key>" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"inv_001"}'

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "error": "Invalid or revoked API key" }

To recover from a supplied invalid or revoked key:

1. Verify the full Authorization: Bearer ... or x-api-key value and check the token copy for truncation or whitespace.
2. Stop retrying the old credential.
3. Issue or obtain a new key through /developers.
4. Update the agent’s secret and send future requests with the new key.

Need to manage or replace a key? Return to the API key management section.

WEBHOOK CONFIGURATION

An invalid webhook_url is a request validation failure and returns 400 before verification runs. The URL must be non-empty, no longer than 2048 characters, use http:// or https://, and contain no URL username or password.

// 400 Bad Request
{
  "error": "invalid_webhook_url",
  "message": "webhook_url must use http:// or https://"
}

Fix it by sending a credential-free HTTP(S) URL. Omit webhook_url to reuse the stored callback, or send null to clear the stored callback. A malformed URL, credentials such as https://user:pass@example.com, an unsupported protocol, and an overlong URL all use the same invalid_webhook_url error with a specific message.

Callback delivery is asynchronous and separate from the inline response. Truss retries non-2xx responses, timeouts, and network failures for three total attempts (the initial delivery plus two retries), records the final failure, and does not change the original valid 200 response. See the API reference’s callback signature and retry guidance for the HMAC header and receiver example.

OTHER SERVER RESPONSES

A server-side failure is not a verification verdict. Retry the generic 500 response with bounded backoff; if it continues, contact Truss with the request timing and context. Once the request reaches verification, all data correctness cases are represented by the stable 200 envelope described above.

// 500 Internal Server Error
{ "error": "Internal server error" }