Errors

Canonical ROS Connect error codes from the runtime catalogue. HTTP aliases such as INTEGRATION_DUPLICATE stay 409.

{
  "success": false,
  "error": {
    "code": "SIGNATURE_INVALID",
    "message": "Invalid signature",
    "requestId": "req_demo"
  }
}

Code	HTTP	Meaning	Resolution	Retryable
`INTEGRATION_NOT_FOUND`	404			No
`INTEGRATION_NOT_CONNECTED`	409	Connection exists but is not in CONNECTED.	Connect the sandbox mock POS from the Developer Console (created with the app).	No until connected.
`INTEGRATION_NOT_IMPLEMENTED`	501	Vendor adapter is declared only.	Do not send production traffic. Use mock POS.	No.
`INTEGRATION_CONFIG_INVALID`	422			No
`INTEGRATION_AUTH_FAILED`	401			No
`INTEGRATION_TIMEOUT`	504			Yes
`INTEGRATION_RATE_LIMITED`	429	Alias of RATE_LIMITED.	Back off 60 seconds.	Yes.
`INTEGRATION_BAD_RESPONSE`	502			Yes
`INTEGRATION_DUPLICATE`	409	Alias of duplicate ingest (HTTP 409).	Same as DUPLICATE_EVENT.	No.
`INTEGRATION_REPLAY`	409			No
`INTEGRATION_UNAUTHORIZED`	403			No
`INTEGRATION_UNSUPPORTED_CAPABILITY`	403			No
`AUTHENTICATION_FAILED`	401	Key id or credential is missing or revoked.	Use the active sandbox API key id from the Developer Console.	No until credentials are valid.
`SIGNATURE_INVALID`	401	HMAC over timestamp + '.' + raw body did not match.	Sign the exact bytes you send. Do not JSON.stringify after signing.	No — fix the signature.
`SIGNATURE_EXPIRED`	401	X-ROS-Timestamp is outside the 5-minute replay window.	Use the current unix seconds and retry once.	Yes, with a fresh timestamp and signature.
`REPLAY_DETECTED`	409	The same signed event was already accepted.	Use a new event id / idempotency key for a new fact.	No — treat as already processed.
`INVALID_SCHEMA`	422	Body failed the X9 envelope/schema.	Compare with the OpenAPI/Postman example for this path.	No until the body is valid.
`INVALID_FIELD`	422			No
`MISSING_REQUIRED_FIELD`	422	A required X9 field was omitted.	Send eventId, eventType, schemaVersion, integrationId, occurredAt, idempotencyKey, data.	No.
`UNSUPPORTED_CAPABILITY`	403	This connection cannot perform that action.	Check GET …/capabilities. Mock POS supports the X9 catalogue; vendor adapters are NOT CONNECTED.	No.
`INTEGRATION_DISABLED`	403			No
`DUPLICATE_EVENT`	409	This event id was already ingested.	Treat as success for retries of the same event.	No — already stored.
`STALE_EVENT`	409			No
`RATE_LIMITED`	429	More than 30 requests / 60 seconds on this connection.	Back off. Honour Retry-After when present.	Yes after the window.
`PROVIDER_TIMEOUT`	504			Yes
`PROVIDER_ERROR`	502			Yes
`IDEMPOTENCY_CONFLICT`	409	Same idempotencyKey with a different payload.	Replay the original body, or mint a new idempotencyKey.	No — payload must match the stored request.
`INTERNAL_ERROR`	500	Unexpected server error.	Retry with the same idempotency key.	Yes.

Honour Retry-After on 429. 4xx duplicate/conflict responses are not retried.