Errors Reference

This page lists the errors a partner can receive from the Integration Framework API, what usually causes each one, and how to fix it.

Most errors use the Problem Details format (application/problem+json) with at least title, status and traceId. The exceptions are the 401 and 403 responses (empty body) and one plain-message 400, marked below. The title values are exact. Include the traceId when you contact ChronosHub support.

Authentication and access

Status	Title	Typical cause	Fix
401 Unauthorized	none (empty body)	The X-Api-Key header is missing, the key is invalid, or the partner it belongs to is inactive.	Send your API key in the X-Api-Key header. If you rotated the key, use the new one.
403 Forbidden	none (empty body)	The key is valid but is not allowed to call the endpoint, in two cases: a non-sandbox key calls a /sandbox/* endpoint (these only work with a sandbox partner's key), or the authenticated identity carries no valid partner id when calling POST /inbound/{eventType}.	Use the API key of the partner the endpoint is meant for. If the key is a normal partner key and you still get 403 on inbound, contact ChronosHub with the time of the request.

Rate limiting

Status	Title	Typical cause	Fix
429 Too Many Requests	Too many requests.	You exceeded the request limit for the endpoint. Rate limits apply to sandbox partners: per partner on the sandbox endpoints and on POST /inbound/{eventType} (which is limited only for sandbox partners), and per client address on anonymous endpoints. Limits reset after a fixed window.	Wait the number of seconds given in the Retry-After response header, then retry. Slow down or batch your calls.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/problem+json

{
  "title": "Too many requests.",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the interval given in the Retry-After header.",
  "traceId": "00-87ca4ab744fecd95c68d7198e8640de9-c9897de70d245733-01"
}

Request validation

Status	Title	Typical cause	Fix
400 Bad Request	One or more validation errors occurred.	A request body is missing a required field or a value is out of range or the wrong format.	Read the errors object: it maps each offending field to a list of messages. Fix those fields and resend.
400 Bad Request	none (not Problem Details)	POST /inbound/{eventType} was sent with an empty or null body. The response body is just the message Payload is required..	Send a JSON object as the body.
400 Bad Request	One or more validation errors occurred.	POST /sandbox/validate or POST /sandbox/outbound-events was sent a payload that is not a JSON object ('Payload' must be a JSON object.).	Send the payload as a JSON object.
400 Bad Request	One or more validation errors occurred.	POST /sandbox/outbound-events/replay was sent a window where to is not later than from, or that is longer than the maximum replay window (Replay window must not exceed N days.).	Send a from and to with to later than from, spanning no more than the maximum number of days.

Example: PUT /sandbox/me/webhook with a webhookUrl that is not an absolute HTTPS URL.

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "WebhookUrl": ["'Webhook Url' must be an absolute HTTPS URL (loopback HTTP is allowed for local development)."]
  },
  "traceId": "00-87ca4ab744fecd95c68d7198e8640de9-c9897de70d245733-01"
}

Inbound events

Status	Title	Typical cause	Fix
400 Bad Request	Payload validation failed	The payload does not match any Active or Deprecated contract version for the event type. The response has eventType, direction and a validationErrors array.	Fix each violation listed in validationErrors and resend. See Inbound Events.
400 Bad Request	No applicable event contract	The event type has no Active or Deprecated contract for your integration: it is misspelled or has not been enabled. The response has eventType and direction.	Check the event type spelling. If it is correct, ask ChronosHub to enable it.
400 Bad Request	Partner Inactive	The request reached an operation for a partner account that is not active. Inactive partners are normally rejected earlier with 401.	Contact ChronosHub.
500 Internal Server Error	Contract evaluation failed	The server could not evaluate your event against its stored contract. This is a fault on our side. The response has eventType and direction.	Retry later. If it persists, contact ChronosHub with the traceId.

Webhook configuration

Status	Title	Typical cause	Fix
400 Bad Request	Webhook Target Not Allowed	A sandbox partner set a webhook URL that resolves to a private or internal address, which is not allowed. This check applies to sandbox partners only.	Use a publicly reachable HTTPS endpoint.
400 Bad Request	Webhook Secret Required	A webhook URL was set but the partner has no saved webhook secret. Sandbox partners always have one, so they don't see this.	Contact ChronosHub.

Sandbox registration

Status	Title	Typical cause	Fix
400 Bad Request	Invite code is invalid or expired	The invite code was mistyped, already used, or has expired.	Check the code. If it still fails, ask ChronosHub for a new invite.
409 Conflict	Duplicate Partner Name	POST /sandbox/register was called with an invite whose organisation name is already a sandbox partner (names are compared case-insensitively).	Ask ChronosHub for an invite in another name.
404 Not Found	Link is invalid or has expired	A secret link was revealed a second time, after it expired, or after a newer link of the same kind replaced it.	Ask for a new link: POST /sandbox/me/api-key/rotate or POST /sandbox/me/webhook-secret/rotate, or, if you never revealed your API key, register again with your invite code.
409 Conflict	Secret link conflict	A secret link was revealed, or a new link requested, at the same moment as another change to your sandbox partner. Nothing was changed and the link is still usable.	Try again.

Sandbox event contracts

Applies to GET, POST and PUT on /sandbox/event-contracts.

Status	Title	Typical cause	Fix
400 Bad Request	Invalid Event Contract Schema	The contract in POST /sandbox/event-contracts or PUT /sandbox/event-contracts/{id} is not a valid contract schema.	Fix the schema as described in detail and resend.
404 Not Found	Event Contract Not Found	GET or PUT /sandbox/event-contracts/{id} named a contract that does not exist, belongs to another partner, or is a shared contract that is not Active or Deprecated (for example a Draft).	Use an id returned by GET /sandbox/event-contracts.
409 Conflict	Owned Event Contract Limit Reached	POST /sandbox/event-contracts would exceed the maximum number of contracts your sandbox partner may own.	Reuse an existing draft with PUT /sandbox/event-contracts/{id} instead of creating a new one.
409 Conflict	Concurrent Event Contract Version	Two requests created the same contract version at the same time.	Retry the request.

Sandbox files

Applies to GET and POST on /sandbox/files, POST /sandbox/files/{id}/link and GET /sandbox/files/{id}/download.

Status	Title	Typical cause	Fix
400 Bad Request	Sandbox File Rejected	POST /sandbox/files refused the upload. detail gives the reason: File limit reached (you already have the maximum number of stored files), File is too large, File is empty, File type '...' is not allowed (the response lists the allowed types), File name is missing or invalid, or no file was sent in the file form field.	Fix the problem named in detail and resend.
413 Payload Too Large	File too large	The POST /sandbox/files request body is larger than the maximum upload size plus a small allowance for the multipart envelope. The detail names the maximum file size.	Send a smaller file.
403 Forbidden	Sandbox File Link Invalid	GET /sandbox/files/{id}/download was called with a missing, altered or expired exp or sig. Download links are valid for 2 hours.	Request a new link with POST /sandbox/files/{id}/link and use the returned url unchanged.
404 Not Found	Sandbox File Not Found	POST /sandbox/files/{id}/link named an id that is neither a sample nor one of your stored files (a file that was removed after its retention period counts as missing), or the file was removed after the link was issued.	Use an id returned by GET /sandbox/files.
503 Service Unavailable	Sandbox File Links Not Configured	The environment has no file link signing key, so links cannot be created or opened.	Try again later, or contact ChronosHub if it persists.

Sandbox validation and outbound trigger

Applies to POST /sandbox/validate, POST /sandbox/outbound-events and the sandbox event reads (GET /sandbox/outbound-events/{id}, GET /sandbox/inbound-events/{id}).

Status	Title	Typical cause	Fix
400 Bad Request	Payload validation failed	POST /sandbox/outbound-events was sent a payload that does not match the applicable outbound contract. The attempt is stored as a rejected outbound event.	Fix the payload as described in detail and resend. Use POST /sandbox/validate to check a payload without sending it.
400 Bad Request	No applicable event contract	POST /sandbox/outbound-events named an event type that has no outbound contract available to your sandbox partner.	Create a contract with POST /sandbox/event-contracts, or use an event type from GET /sandbox/event-contracts.
500 Internal Server Error	Contract evaluation failed	POST /sandbox/outbound-events could not evaluate your payload against the applicable contract. This is a fault on our side. The response has eventType and direction.	Retry later. If it persists, contact ChronosHub with the traceId.
409 Conflict	Sandbox Webhook Not Configured	POST /sandbox/outbound-events was called before your sandbox partner had a webhook URL.	Set the URL with PUT /sandbox/me/webhook, then trigger the event again.
404 Not Found	Outbound Event Not Found / Inbound Event Not Found	GET /sandbox/outbound-events/{id} or GET /sandbox/inbound-events/{id} named an event that does not exist or belongs to another partner.	Use an id from GET /sandbox/outbound-events or GET /sandbox/inbound-events.

Server errors

Status	Title	Typical cause	Fix
500 Internal Server Error	An unexpected error occurred.	An unexpected fault on our side.	Retry later. If it persists, contact ChronosHub with the traceId.

Management-only errors

The ChronosHub management API (used by ChronosHub staff, not partners) has further errors that you will not see: partner, event and sandbox invite not-found errors (404), shared event contract lifecycle conflicts (409), and a missing change summary (400). They are omitted here. Errors from the sandbox event contract endpoints are listed above.