{"schemaVersion":"mappls.error-catalog.v1","summary":{"classes":11,"runtimes":8,"normalizedOperationsConsidered":162,"operationsWithResponseEvidence":162,"documentedResponseStatuses":["200","201","203","204","206","400","401","403","404","405","406","409","412","422","500","503"],"maintainedSdkCodeSignals":51},"rules":["Classify before retrying: authentication, authorization, validation, conflict, and unknown outcomes need different recovery.","HTTP status is a transport clue, not a provider-wide payload contract; exact API/SDK generation and issued account remain authoritative.","A read may be retried within a budget; a state change that timed out must be reconciled by stable identity before replay.","Support packets contain minimized identities and timing—not credentials, full URLs, customer payloads, precise-location history, media, or response bodies.","Fixtures, normalized contracts, and maintained SDK signals are implementation evidence; they never claim live availability or universal error codes."],"options":{"runtimes":["rest","server-sdk","web-sdk","mobile-sdk","widget","mcp","webhook","control-plane"],"operationSafety":["read","idempotent-write","non-idempotent-write","state-transition","unknown"]},"classes":[{"slug":"local-configuration","title":"Local configuration failure","severity":"caller","statusCodes":[],"defaultRetry":"fix-then-retry","summary":"The integration could not safely construct or start the request because local endpoint, credential, package, or runtime configuration is incomplete or unsafe.","codeSignals":["insecure_endpoint","credential_required","intouch_credential_required","invalid_configuration","sdk_not_initialized"],"whatHappened":"No provider success should be assumed. The failure occurred at or before the application adapter boundary.","likelyCauses":["Missing or mismatched credential generation","HTTP endpoint outside an explicit loopback test","SDK initialized in the wrong lifecycle or with incompatible packages","Release configuration differs from development"],"firstChecks":["Choose the exact product/runtime authentication path","Compare safe endpoint host, SDK version, build variant, origin/package/bundle identity, and region","Confirm the provider request was never sent before retrying"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Correct configuration","Run one bounded non-production probe","Record the selected generation and release proof"],"statefulRecovery":["Keep the aggregate unchanged","Correct configuration","Reconcile any adapter queue before resuming commands"],"links":[{"label":"Authentication center","href":"/authentication"},{"label":"SDK center","href":"/sdks"}],"samples":[{"language":"typescript","label":"Classify without leaking provider data","code":"try {\n  const client = createMapplsClientFromEnvironment();\n  await client.geocode({ address });\n} catch (error) {\n  // Record only error.code, status, runtime, release, and request ID.\n  // Never serialize the client, environment, URL, or credential.\n  throw toSafeApplicationError(error);\n}"}]},{"slug":"validation","title":"Request validation failure","severity":"caller","statusCodes":[400,405,411,413,415,422],"defaultRetry":"fix-then-retry","summary":"The request shape, value range, content type, method, or business precondition is invalid for the selected contract.","codeSignals":["invalid_location","invalid_profile","location_limit","invalid_history_window","invalid_argument","invalid_request","validation_failed"],"whatHappened":"The operation was rejected as submitted. Repeating the same request cannot make it valid.","likelyCauses":["Wrong coordinate order, field name, enum, timestamp unit, or bound","Required field or content type missing","Request built for another API or SDK generation","A state transition precondition is not satisfied"],"firstChecks":["Open the exact normalized operation rather than a neighboring guide","Validate method, host, path, auth generation, required fields, units, and maximums","For transitions, reload current state and allowed commands"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Fix the invalid field or contract selection","Add a regression test for the rejected boundary","Retry once with a new request identity if required"],"statefulRecovery":["Do not mutate local state optimistically","Reload the aggregate and allowed transition","Submit a corrected command with a stable idempotency key"],"links":[{"label":"API reference","href":"/api-reference"},{"label":"Credential-free sandbox","href":"/sandbox"}],"samples":[]},{"slug":"authentication","title":"Authentication rejected","severity":"policy","statusCodes":[401],"defaultRetry":"fix-then-retry","summary":"The credential is missing, expired, revoked, malformed, or belongs to a different product generation or transport.","codeSignals":["unauthorized","authentication_failed","invalid_token","token_expired","oauth_rejected"],"whatHappened":"The caller identity was not accepted. Blind retries can amplify an outage or lockout and must stop.","likelyCauses":["Current static key, legacy OAuth, InTouch bearer, app key, or MCP token was interchanged","Credential expired, was rotated, or is not present in the intended runtime","Host/path generation or Authorization transport is wrong","Clock skew or issuer/audience mismatch"],"firstChecks":["Stop automatic retries","Compare the selected authentication path and issued generation","Rotate only through the controlled overlap-and-drain lifecycle"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Correct credential selection or refresh through the approved provider","Prove one non-production request","Resume bounded traffic without logging token text"],"statefulRecovery":["Pause commands","Refresh or rotate identity","Reconcile queued and unknown outcomes before resuming"],"links":[{"label":"Authentication center","href":"/authentication"},{"label":"Credential console","href":"/console/credentials"}],"samples":[]},{"slug":"authorization-entitlement","title":"Authorization or entitlement denied","severity":"policy","statusCodes":[403],"defaultRetry":"do-not-retry","summary":"Identity may be valid, but the application, product, scope, region, origin, signing identity, resource, or action is not permitted.","codeSignals":["forbidden","insufficient_scope","not_entitled","meter_target_not_entitled","meter_region_mismatch","policy_denied"],"whatHappened":"The requested capability is outside the verified caller's current authority.","likelyCauses":["Product or quota was not provisioned","Origin, server egress, Android signing identity, iOS bundle/team, asset, or region does not match","Human or service actor lacks transition authority","MCP deployment profile or OAuth scope excludes the tool"],"firstChecks":["Keep restrictions in place","Inspect entitlement and credential metadata in the console","Request the narrow missing access with product, environment, region, and business purpose"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Obtain or correct least-privilege entitlement","Prove the exact runtime restriction","Retry only after control-plane evidence changes"],"statefulRecovery":["Keep the command pending or rejected according to the journey","Record the decision trail","Resume only after entitlement activation is independently observed"],"links":[{"label":"Applications","href":"/console/applications"},{"label":"Authentication center","href":"/authentication"}],"samples":[]},{"slug":"not-found","title":"Resource or route not found","severity":"caller","statusCodes":[404,410],"defaultRetry":"do-not-retry","summary":"The endpoint generation, operation path, tenant-owned resource, Mappls Pin, asset, or durable aggregate is absent or no longer addressable.","codeSignals":["not_found","resource_not_found","application_not_found","gone"],"whatHappened":"The selected identity was not found at the queried boundary; this is not proof that a similarly named resource exists elsewhere.","likelyCauses":["Wrong host/path or legacy/current generation","Resource belongs to another tenant, region, project, or environment","Identifier is stale, deleted, retired, or never committed","Read-after-write convergence is still pending"],"firstChecks":["Confirm exact resource type and environment","Use a supported list/read contract where available","For a recent write, reconcile by idempotency key or provider request ID"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Correct the identifier or endpoint generation","Do not enumerate foreign resources","Treat 410 as retired unless the contract says otherwise"],"statefulRecovery":["Reconcile command and event history","Distinguish pending convergence from terminal absence","Require a new command for recreation rather than silently reusing identity"],"links":[{"label":"API reference","href":"/api-reference"},{"label":"Stateful planner","href":"/tools/stateful"}],"samples":[]},{"slug":"conflict","title":"Conflict or stale state","severity":"stateful","statusCodes":[409,412,428],"defaultRetry":"reconcile-first","summary":"The command conflicts with a committed version, reused identity, transition invariant, duplicate content, or concurrent operation.","codeSignals":["conflict","version_conflict","already_exists","idempotency_conflict","meter_event_conflict","meter_request_conflict"],"whatHappened":"A durable decision already exists or the caller acted on stale state. The outcome cannot be resolved by changing only the retry delay.","likelyCauses":["Optimistic version is stale","An idempotency key was reused with different content","The transition already completed or is no longer allowed","Two actors attempted incompatible changes"],"firstChecks":["Read the latest aggregate version and event/audit evidence","Compare a safe request-content digest—not the payload—against the original command","Decide whether the intended business outcome is already satisfied"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier","Aggregate ID, expected/current version, idempotency-key hash, and command type"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Correct the stale precondition","Use a fresh request identity only for a genuinely new operation","Never turn a conflicting duplicate into an automatic new write"],"statefulRecovery":["Reconcile current aggregate and provider state","Return the already-committed result when the original intent matches","Otherwise require an explicit new versioned command"],"links":[{"label":"Stateful operations","href":"/tools/stateful"},{"label":"Event catalog","href":"/events"}],"samples":[]},{"slug":"rate-limited","title":"Rate or quota limited","severity":"transient","statusCodes":[429],"defaultRetry":"retry-after","summary":"A provider, gateway, tenant policy, or product quota is intentionally limiting work.","codeSignals":["rate_limited","quota_exceeded","too_many_requests","budget_exhausted"],"whatHappened":"Capacity or policy denied this attempt. Immediate parallel retries make recovery slower and may consume more budget.","likelyCauses":["Burst or sustained rate exceeded","Monthly entitlement or tenant delivery budget exhausted","Retry storm or missing client-side coalescing","One workload is starving others"],"firstChecks":["Honor Retry-After when present","Inspect application/product usage and quota","Reduce concurrency, coalesce duplicate reads, and add jitter"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier","Retry-After value and safe quota-policy version"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Wait for Retry-After or a bounded exponential backoff with jitter","Cap attempts and total elapsed time","Cache or batch where the contract permits"],"statefulRecovery":["Keep the command durably queued","Schedule a later attempt without changing idempotency identity","Preserve per-aggregate ordering and tenant fairness"],"links":[{"label":"Usage console","href":"/console/usage"},{"label":"Request diagnostics","href":"/console/logs?outcome=throttled"}],"samples":[]},{"slug":"timeout-network","title":"Timeout or network failure","severity":"transient","statusCodes":[408,504],"defaultRetry":"bounded-retry","summary":"The client did not receive a trustworthy completion response before its deadline, or could not establish the network request.","codeSignals":["timeout","network_error","connection_reset","dns_failure"],"whatHappened":"For reads, completion is usually absent. For writes and transitions, the provider may have committed even though the response was lost.","likelyCauses":["Client deadline too short","DNS, TLS, proxy, mobile/offline, or provider connectivity failure","Large or expensive request","Response was lost after a stateful commit"],"firstChecks":["Classify the operation safety before retrying","Retain request ID, idempotency identity, deadline, attempt, and occurrence time","Check service status and local network without exposing the request URL"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier","Idempotency key hash and reconciliation lookup result for writes"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Retry an idempotent read within an attempt and elapsed-time budget","Use jitter and a fresh transport connection where appropriate","Surface a bounded unavailable result after exhaustion"],"statefulRecovery":["Mark outcome unknown","Query by provider request or idempotency identity","Retry the same command identity only when the contract proves idempotency"],"links":[{"label":"Platform status","href":"/status"},{"label":"Request diagnostics","href":"/console/logs"}],"samples":[]},{"slug":"provider-unavailable","title":"Provider or dependency unavailable","severity":"transient","statusCodes":[500,502,503,507],"defaultRetry":"bounded-retry","summary":"A provider, gateway, dependency, or adapter failed to serve a valid response.","codeSignals":["provider_error","oauth_unavailable","oauth_invalid_response","service_unavailable","dependency_unavailable"],"whatHappened":"The operation did not return a usable success. Stateful mutation outcome may still be unknown unless the contract proves rejection-before-commit.","likelyCauses":["Provider or gateway incident","Upstream returned malformed or incomplete data","Dependency saturation or rollout regression","Regional routing or entitlement adapter unavailable"],"firstChecks":["Check request diagnostics and public status","Compare error rate by operation, application, region, and release","Use request ID for provider correlation and keep response bodies out of tickets"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Use bounded exponential retry only for safe reads","Open a circuit after the retry budget","Serve an explicit stale/partial fallback only when product semantics permit"],"statefulRecovery":["Move the command to unknown or retry-scheduled state","Reconcile before reissuing","Preserve the same idempotency identity and ordering lane"],"links":[{"label":"Platform status","href":"/status"},{"label":"Request diagnostics","href":"/console/logs?outcome=server-error"}],"samples":[]},{"slug":"unknown-outcome","title":"Unknown stateful outcome","severity":"stateful","statusCodes":[202],"defaultRetry":"reconcile-first","summary":"A command was accepted or lost across an asynchronous boundary, but final provider and application state are not yet reconciled.","codeSignals":["unknown_outcome","provisioning_pending","callback_pending","delivery_unknown","reconciliation_required"],"whatHappened":"Neither success nor failure is safe to claim. A second business command could duplicate work or violate ordering.","likelyCauses":["Accepted asynchronous work has not completed","Callback or webhook is delayed or missing","Response was lost after commit","Application and provider inventories disagree"],"firstChecks":["Keep the original idempotency and provider request identities","Read aggregate, outbox, callback, delivery, and provider evidence","Escalate only a minimized support packet after the reconciliation deadline"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier","Aggregate/version, command type, idempotency-key hash, provider request ID, last observed state, and reconciliation deadline"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Do not use this class for a truly stateless read","Reclassify from the actual HTTP/error evidence"],"statefulRecovery":["Persist unknown outcome explicitly","Reconcile by stable identity","Apply the observed terminal event once","Require independent recovery approval where replay has material effect"],"links":[{"label":"Stateful operations","href":"/tools/stateful"},{"label":"Application events","href":"/events"}],"samples":[]},{"slug":"unclassified","title":"Unclassified failure","severity":"unknown","statusCodes":[],"codeSignals":[],"defaultRetry":"reconcile-first","summary":"The available status and code are insufficient to select one safe recovery path.","whatHappened":"The failure must remain unclassified until the exact runtime, operation, status, and safe code are known.","likelyCauses":["SDK callback omitted a status","A wrapper replaced the provider error","Multiple generations use the same informal message","Only human-readable text was captured"],"firstChecks":["Capture a bounded status, code, runtime, operation, and request ID","Identify whether the action is a read or state change","Use the exact API/SDK guide and release version"],"safeEvidence":["Request ID or correlation ID, if returned","UTC occurrence time, application ID, product, operation, region, and runtime","HTTP status and a bounded, non-sensitive error code","Attempt count, timeout, SDK/package version, and release identifier"],"neverCollect":["Keys, tokens, client secrets, Authorization headers, or signed URLs","Full request URLs when a credential may be in the query string","Customer payloads, precise-location history, media, or response bodies by default"],"statelessRecovery":["Do not retry until the operation and failure class are known"],"statefulRecovery":["Preserve state and mark outcome unknown","Reconcile before any replay"],"links":[{"label":"Request diagnostics","href":"/console/logs"},{"label":"Support","href":"/support"}],"samples":[]}]}