Runtime, errors and security

This page defines the integration control plane shared by every capability. Exact operation-specific headers, schemas, status codes and error examples remain in OpenAPI.

Base URL and authentication

• Base URL: https://api.tapinomahub.com
• Default authentication scheme: API key in the X-Api-Key request header. It applies to every documented operation, including GET /ping.
• Intelligence operations additionally declare a verified first-party session cookie as an alternative for explicitly enabled accounts. Server integrations should use X-Api-Key; a session-authenticated Intelligence POST must also send X-CSRF-Token when that operation declares it.
• Production and sandbox use the same base URL; the key selects the environment.

Keep API keys in a server-side secret store. Never place them in a browser bundle, mobile-app binary, redirect URL, query parameter, log, analytics event, screenshot, support ticket or documentation console.

Use a separate Client and key when customer, application, quota, usage or billing isolation is required. A Tenant in the customer system is not an API field.

Minimal client policy

Every production adapter should have one shared response wrapper that:

1. records the operation ID, HTTP method and path template without recording secrets;
2. captures HTTP status and the documented operational headers;
3. parses JSON only when the response media type and operation declare it;
4. on non-2xx, branches on the stable top-level error code and never on message;
5. on a job-status 200, branches again on the job's domain status;
6. rejects a payload that does not satisfy the pinned OpenAPI schema;
7. returns a typed domain result to the calling ERP, DMS, shop or worker.

Do not build each endpoint as an unrelated HTTP call. Authentication, retry, idempotency, async state, tenant isolation and observability must be consistent across the adapter.

Response decision matrix

The same error code can require evaluation together with HTTP status. Apply only the retry behaviour documented for the selected operation and response status.

In a successful base-part response, part.name is a string or null when available. Preserve the returned value, and do not reconstruct a missing name from another field. fitment contains the available type-level assignments and can be empty.

Error object

The common non-2xx body is:

{
  "error": "stable_machine_code",
  "message": "Human-readable explanation"
}

Only error is a program key. message can be localized or reworded. The OpenAPI contract documents retry behaviour and operation-specific schemas and examples determine which codes are evidenced on each status; extra response fields remain governed by that response schema.

Do not assume that the global catalogue alone proves that every error applies to every operation. Use only errors documented for the selected operation and status.

Asynchronous jobs

9 public operations can return 202; they form 6 documented job families. The two Intelligence status operations themselves return 202 while work remains pending and therefore count as operations with a 202, not as additional job families.

The two Intelligence job families are conditional pilot contracts. Adaptive part refresh and VIN Economic Intelligence are currently disabled in production; their initiating routes return the documented error branches when work would have to be started. Apply the polling rows below only after the corresponding feature has been enabled or to a job that was already accepted.

GET /parts/clusters/{clusterId}/history has no asynchronous branch and never creates missing history.

Generic polling flow:

send order once
  -> final 2xx: validate and complete
  -> 202:
       validate the required absolute statusUrl against the documented status operation
       compare Location with statusUrl; quarantine a mismatch
       persist workflow family + jobId + nextPollAt
       wait at least Retry-After seconds
       GET statusUrl
         -> HTTP 202 queued/running where declared: update nextPollAt and wait
         -> HTTP 200 status resource: inspect its domain status
         -> succeeded/final result: require the workflow's usable result, or quarantine
         -> failed: require/map the workflow's embedded error, or quarantine

Polling the six documented status families belongs to the original order and does not create a second order. The current Intelligence pilot remains closed until approved positive pricing and atomic billing are enabled together; no real result is released before then. Test every documented HTTP and domain-status branch against its schema.

Do not infer lifecycle behaviour that the selected operation does not document.

Idempotency

The support signal is the operation's declared Idempotency-Key header parameter. Do not infer support merely because the method is POST, PUT, PATCH or DELETE.

For an operation that declares the header:

1. Generate one opaque key for one logical business action.
2. Persist it before sending the request.
3. Reuse the same key after a timeout or other ambiguous transport failure.
4. Never reuse it for a different request.
5. Keep the key scoped to the Client and business action in local storage.

The Intelligence resolver, current-cluster and history GET operations are explicit exceptions to the usual read convention: each requires Idempotency-Key. Their two status-polling GET operations accept only jobId and do not declare that header. Follow the selected operation rather than deriving idempotency from its HTTP method.

The central replay details below apply only where the selected operation declares the corresponding response headers and error codes. The four initiating Intelligence pilot operations document X-Tapinoma-Idempotent-Replay and 409 idempotency_key_conflict, but not X-Tapinoma-Idempotency-Stored, idempotency_request_in_progress, idempotency_result_unavailable or a 24-hour retention promise. Do not infer those central behaviours for an Intelligence request.

Documented behaviour:

• A completed repeat returns the earlier response without re-execution or a second charge and sets X-Tapinoma-Idempotent-Replay: true.
• The first successful response reports X-Tapinoma-Idempotency-Stored: true|false.
• false means the same key returns 409 idempotency_result_unavailable; do not switch automatically to a new key.
• While the first call is active, the same key can return 409 idempotency_request_in_progress. Repeat the unchanged request after Retry-After.
• Earlier successful results remain retrievable with the same key for 24 hours.
• For a failed call, follow the documented error code, refund rule and retry guidance.
• The key space is per Client. The same key with a different request returns 409 idempotency_key_conflict.

The renamed scanner paths use compatibility aliases rather than HTTP redirects. Follow the documented request, response and idempotency behaviour for each alias pair:

• /scanner/document/registration and deprecated /scanner/registration-document;
• /scanner/document/registration/international and deprecated /scanner/registration-document/v2;
• /scanner/document/vehicle and deprecated /scanner/vehicle-document/extract.

For these three pairs, an identical body and key may be retried through either path and returns the same stored result without re-execution or a second charge. Calculation extraction is deliberately not an identical response pair: /scanner/document/calculation returns 12 top-level fields including equipment, while deprecated /scanner/document/extract retains the 11-field response without it. Reusing a key across those two response contracts returns HTTP 409; repeat an ambiguous request only on the same path contract.

The three key-issuing operations deliberately do not support idempotency:

• POST /client/users
• POST /client/users/{clientId}/keys
• POST /client/partner-workspaces

Their success payload contains a new plaintext API key and cannot be repeated safely after an uncertain outcome. Enter an operation-specific reconciliation_required state and never repeat the write blindly. POST /client/users can use GET /client/users to determine whether a Client was created, but that list cannot recover the lost plaintext key. The public contract exposes no raw-key recovery for POST /client/users/{clientId}/keys and no partner-workspace lookup by externalReference; those two outcomes require an operator-approved recovery procedure.

Retry policy

Use the global error catalogue, HTTP status and operation contract together.

if final success:
  do not retry
else if 202:
  poll the validated full statusUrl; do not resend order
else if response.error is not marked retryable:
  stop or request corrected state/input
else if Retry-After exists:
  wait at least that duration
else:
  use bounded exponential backoff with jitter

for an ambiguous supported write:
  retry with the same Idempotency-Key
for an unsupported key-issuing write:
  enter operation-specific reconciliation_required
  use published list state only where it exists
  require operator-approved recovery when the public contract is insufficient
  never repeat blindly

The exact maximum attempt count and time budget are customer-system policies; the API contract does not publish universal values. Keep the total below the calling system's business deadline and surface exhaustion as an operational state.

Rate limits and concurrency

Rate limits attach to a Client and endpoint_key. Client-specific overrides can target one endpoint key or *. When no override exists, technical defaults apply, but the numeric defaults are not published.

Independent of numeric rate limits, only one API request may be active per Client. Another concurrent request is rejected with 429 client_request_in_progress. This is not a contract-partner-wide cap: separate Clients can run in parallel.

Recommended queue shape:

queue key = clientId (or local Client mapping)
concurrency per queue = 1
cross-Client workers = bounded by the partner's own resources and agreed limits
429 -> read error + Retry-After -> reschedule, do not busy-loop

When effective numeric defaults are not published, do not hard-code guessed requests-per-minute values. Use only limits supplied through an approved contract or documented mechanism.

Pagination

The contract's long-list pattern uses:

• limit: 1 to 500
• offset: page offset; valid only together with limit
• count: total result count
• page.returned: length of this page
• page.hasMore: whether another page follows

API 1.71.0 exposes this pattern on the OE aftermarket-reference list and the VDI catalogue. Without limit, the contract says the complete result is returned. Every page is a separate call and is billed as a call, so a complete unpaginated read remains cheapest when its size is operationally acceptable.

Use page.hasMore, not items.length === limit, as the continuation signal. Keep the same query semantics across pages and validate the selected operation's response schema.

Operational response headers

Read only headers declared by the selected operation. The global vocabulary includes:

Header names are case-insensitive. Their values are not substitutes for validating the response body.

Billing-aware behaviour

• Chargeable endpoints have a list price; contractually agreed terms prevail.
• A plan is assigned per endpoint_key, not globally to a Client.
• Different endpoint keys can be covered by different active plans.
• If no active plan covers the endpoint, or its monthly quota is exhausted, billing falls back to the Client's credit balance.
• VIN vehicle, VIN parts and VIN cart check share the documented monthly VIN bundle rule per Client and VIN.
• From 90% plan consumption, the API can emit X-Tapinoma-Usage-Warning.
• A pre-charged individual call ending with HTTP status 400 or above is generally refunded exactly once, subject to the two explicit combined-VIN exceptions and the documented no-content rule.

Do not calculate customer invoices from a single response header. Reconcile usage and balance with GET /client/usage or the Master client view GET /client/users/{clientId}/usage.

Timeouts

Only an operation carrying x-client-timeout-seconds publishes a client timeout recommendation through the contract. API 1.71.0 declares 300 seconds for the part-composite, part-damage-transfer and identifier-redaction Vision operations. Do not apply this number globally.

For asynchronous operations, the synchronous request timeout and the job's total processing lifetime are different concepts. Follow the returned job URL and Retry-After until a documented terminal state is reached.

Response handling

• Use request and response data only within the rights and duration agreed for the integration.
• Never share request or response data across Clients or customer-system Tenants.
• Keep raw document and image URLs out of general application logs.
• Record the OpenAPI version, operation ID, input identity and result time with any permitted derived record.
• Do not turn a negative result into a permanent fact.
• Honour operation-specific Cache-Control or expiry fields when present.

File, image and document security

• Send only content for which the caller holds the required rights, consents and lawful basis.
• Minimize personal data to the selected purpose.
• Use the exact URL-scheme, size, redirect and media-type constraints of the selected operation; prefer HTTPS wherever that contract permits it.
• Signed query parameters can contain secrets; redact them from logs and provenance views unless the contract explicitly returns a sanitized form.
• Treat OCR and Vision output as derived evidence, not automatically verified master data.
• Keep original media, transformed media, provenance, business approval and publication state as distinct records.
• Never infer that tapinomahub stores or deletes a remote source file on a particular schedule; rely only on an explicitly approved retention policy.

Redirect security

For POST /vin/redirect-sessions:

• create the session from the backend;
• send the API key only in that backend request;
• redirect the browser only to the returned redirectUrl;
• use a caller-owned, unpredictable state value to correlate the callback when supplied;
• verify that returned state equals the stored value;
• accept only the documented callback fields;
• keep callback state single-use in the customer application.

The contract says an empty state is treated as unset and omitted from the callback. It does not turn state into an authentication credential; the customer application remains responsible for securing its callback session.

Contract pinning and upgrades

Pin generated client types and contract tests to the published info.version. Validate responses against the selected schema: reject or quarantine additive fields when that schema is closed with additionalProperties: false, and accept them only where the schema explicitly permits additions. A transport layer may capture a redacted response for controlled diagnostics when the approved data policy permits it, but the business projection contains only documented fields. Fail validation when a required field, enum or response shape changes unexpectedly.

Do not infer semantic-version guarantees from the version string alone; review contract changes before automating upgrades.