Troubleshooting and support

Start with the HTTP status, the response body, and the endpoint you called. Retry only when the failure can reasonably be temporary.

Find your symptom#

I received HTML#

Check the URL first. /mt-backend/ opens the guide and /mt-backend/swagger/ opens the reference; API requests use /mt-backend/api/v1/ followed by an endpoint such as repositories. developer.2c8.com hosts documentation, not your organization's data. Replace example hosts with your server address. A proxy or login gateway can also return an HTML page; check the status, content type and any redirect before treating the body as JSON. Ask your administrator about network or VPN access if you cannot reach the server.

The list is empty#

An HTTP 200 with data: [] is a successful request with no results on that page. Clear filters, set startAt=0, and confirm the server and repository with your administrator. The selected repository may simply contain no models. If total is nonzero, check the offset and pagination. Do not assume that an empty list means the key is invalid.

There are no model names#

For the model list, use projection=SIMPLE and fields=titles. The compact projection alone contains uuid and modelType, not names. Expand data, then titles, then a language UUID, and read title. Names are not returned as a top-level name field on a model. If the requested language is missing, follow the catalogue walkthrough.

The example command does not run#

The commands use Bash, including Git Bash or WSL on Windows. They are not PowerShell or Command Prompt syntax. Keep the trailing \ at each continued line with no spaces after it, and replace the server address and ID placeholders. “curl: command not found” means cURL is not available in that shell. “unknown option --fail-with-body” means its cURL version is too old for these examples; update cURL or use the guided Swagger route.

Typing the API key at the Bash prompt intentionally displays no characters. If a request returns 401, confirm the variable was set in the same shell and that the key belongs to this server. Avoid verbose/debug command output when sharing a problem, because it can expose headers.

Swagger has no Execute button#

The public reference cannot execute requests. Open Swagger on your own server, expand the operation and choose Try it out. Its Server response appears after executing; Example Value is sample documentation. See the quickstart.

Diagnose a failed request#

Do not blindly repeat create/update/delete requests after a timeout or server error: the operation may already have taken effect. Verify the resulting state first.

Read an error response#

Common API errors return a message and timestamp:

{
  "message": "Authentication required to access this resource.",
  "timestamp": "2026-09-10T10:00:00Z"
}

The HTTP status is carried by the response itself. This example is illustrative; validation errors and rate-limit errors can use other bodies. A reverse proxy can also return HTML or an empty response, so do not assume every failed request contains this JSON shape.

Rate limits#

Rate limiting is configurable per installation and tracked per authenticated identity. API keys can be configured to use rate limiting; not every key or request receives rate-limit headers. The limiter skips OPTIONS requests, requests without a principal, and keys configured without rate limiting. A named anonymous principal, such as the one used for public access to /versions, is still subject to the limiter.

When provided, these headers describe the current limit:

Example rate-limit response body:

{
  "error": "Rate limit exceeded",
  "message": "Maximum 60 requests",
  "retryAfterSeconds": 12
}

The numbers above are examples, not a published quota. The backend's Retry-After header and retryAfterSeconds body field carry the same non-negative wait in seconds. Ask the administrator about the limit configured for your installation. Quota headers can also appear on successful responses and on other failures if the limiter ran; they are not guaranteed on errors rejected before it runs.

Retry a throttled read#

1. Wait at least the returned Retry-After duration and add a small random delay (jitter) so workers do not all retry together. Reduce request concurrency.
2. Set both an attempt limit and an elapsed-time budget. For example, allow at most three retries within 60 seconds; this is a suggested client policy, not a server setting.
3. If the next wait would exceed your budget, stop and report the throttling response. Avoid an immediate retry loop when the wait is zero. A retry can still receive 429.

Check a write before repeating it#

A confirmed 429 from this backend filter rejects the request before the resource operation runs. A write can be retried after that rejection using the returned wait and a bounded retry budget, provided no earlier attempt has an uncertain outcome.

After a timeout, lost connection or server error, a create/update/delete operation may already have taken effect. Read back the resulting state and reconcile it before resubmitting. Receiving 429 on a later attempt does not tell you whether an earlier attempt succeeded. Responses from a proxy may have different bodies and behavior.

Versions and compatibility#

The API path contains v1. The backend release is a separate version, displayed in this guide's navigation/footer. A SNAPSHOT suffix identifies a development build, not a final release. A static export also shows when the documentation was exported; that timestamp is not the API version or release date.

To identify a deployed installation:

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $API_KEY" \
  "$API_BASE_URL/versions"

The response includes mtBackendVersion and dbVersion. When using a publicly hosted documentation snapshot, check its server-release label against your installation. Its Swagger and downloads do not necessarily describe an older server.

Use documented fields and operations, tolerate additional response fields, and validate your integration when upgrading. This guide does not establish a compatibility or deprecation policy.

Contact support#

Contact support@2c8.com. Include:

• The server release and approximate time of the failure, including time zone.
• The HTTP method, endpoint path, status, and error message.
• A minimal request example with API keys, authentication headers, and sensitive content removed.
• The expected result and whether the problem occurs consistently.

If you host the server, check its logs for the same time period.

Glossary#