Errors and Status Codes

Common Status Codes

Status	Meaning	Typical action
200	Request succeeded	Continue the workflow; validation results can still be negative.
400	Invalid request	Correct the path, query parameters, or request body.
401	Authentication failure	Obtain a valid access token and verify its scope. See Authentication and Authorization.
404	Organisation or requested resource not found	Verify the Swiss enterprise identification number (UID), name, route, and relevant register.
429	Quota or rate limit exceeded	Read the RateLimit-* headers and wait for the indicated reset interval.
500	Internal server error	Retry only if safe; contact support if the error persists.
502	An upstream gateway or dependency failed during a lookup	Retry the lookup with backoff; contact support if the dependency remains unavailable.

Error Handling Pattern

1. Log the request ID and endpoint.
2. Parse the error body and correlate it with the operation.
3. Retry only when the operation is safe and the failure is transient.
4. Escalate with request metadata for support cases.