Errors - The Data City

The Instant Classification API uses standard HTTP status codes. Error responses include a JSON body with a detail field describing what went wrong.

Error envelope

{
  "detail": "Human-readable description of the error."
}

The detail wording may change between releases — match on status codes in your error handling, not on the string.

429 is the exception. Rate-limit responses use an error key instead of detail:

{
  "error": "Rate limit exceeded: 5 per 1 minute"
}

Read both keys when logging errors, or you’ll record an empty message for every throttled request.

Status code matrix

Status	When to expect it	What to do
`200`	Successful classification.	Process the response body.
`400`	Invalid request: bad JSON, empty body, rejected input, or wrong login credentials. Also returned for an inactive account.	Read `detail`, fix your request, and retry.
`401`	No `Authorization` header, or the token is expired, malformed, or no longer identifies an account.	Get a new token from `/api/v1/login/access-token`. See Authentication.
`402`	Free-tier usage quota exceeded.	Contact support@thedatacity.com for a paid plan. See Rate limits.
`422`	Request failed schema validation: `Text` over 1,000 characters, `Website` over 500, or Terms & Conditions not accepted on signup.	Read `detail` and adjust the request.
`429`	Rate limit exceeded, on classification or on the login endpoints.	Back off and retry. See Rate limits.
`500`	Unexpected server error.	Retry with exponential backoff. If persistent, contact support@thedatacity.com.
`502`	The upstream classification engine returned an error.	Retry after a short delay.
`503`	Classification engine unreachable or timed out after server-side retries.	Retry after a longer delay (30+ seconds).
`504`	Rare. A timeout that surfaced outside the normal retry path.	Treat it like `503`.

Any credential problem is a 401: no header, an expired token, a malformed one, or a token whose account no longer exists. Refresh on 401 and retry once.The API returned 403 for expired tokens until July 2026. If your client still keys on 403, update it.

Retrying

Retry 429, 500, 502, 503, and 504 with exponential backoff:

attempt 1 → wait 2 s
attempt 2 → wait 4 s
attempt 3 → wait 8 s
attempt 4 → give up, surface the error

Add random jitter (0–500 ms) so concurrent clients don’t synchronise retries.

Do not auto-retry 400, 402, or 422. The same request will fail the same way. For 401, get a new token first: retrying with the same one keeps failing.

The API already retries the upstream engine up to four times before it gives up, so a 503 means several attempts have failed. Wait longer than you would for a 500.

Common error scenarios

Classification returns 400

The most likely cause is an empty request body. You must supply either Text or Website (not both):

{"Text": "Software development and consulting"}

{"Website": "https://example.com"}

Text is capped at 1,000 characters and Website at 500 characters. Exceeding either limit returns 422.

Classification returns 402

Your free-tier quota is exhausted. The free tier does not reset — contact support@thedatacity.com for a paid plan.

Classification returns 502 or 503

The upstream classification engine is temporarily unavailable. This is usually transient. Wait 30 seconds and retry. A timeout also arrives as 503, because the API wraps timeouts in its own retry handling before returning. Don’t wait for a 504.

Classification hangs, or your client times out

Each upstream attempt gets up to 30 seconds, and the API makes up to four attempts with 1s, 2s and 4s waits between them. A slow request can therefore run for well over a minute before it either succeeds or fails. Set your client timeout to at least 120 seconds on this endpoint. A short client timeout is the most common cause of failures that look like API errors but are actually the client giving up early.

​Error envelope

​Status code matrix

​Retrying

​Common error scenarios

​Classification returns 400

​Classification returns 402

​Classification returns 502 or 503

​Classification hangs, or your client times out

Error envelope

Status code matrix

Retrying

Common error scenarios

Classification returns 400

Classification returns 402

Classification returns 502 or 503

Classification hangs, or your client times out