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."
}
detail wording may change between releases — match on status codes in your error handling, not on the string.
Status code matrix
| Status | When to expect it | What to do |
|---|
200 | Successful classification. | Process the response body. |
400 | Invalid request — bad JSON, missing fields, malformed input, or wrong credentials. | Read detail, fix your request, and retry. |
401 | Missing, malformed, or expired Bearer token. | 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 well-formed but semantically invalid (e.g. Terms & Conditions not accepted on signup). | Read detail and adjust the request. |
429 | Per-minute rate limit exceeded. | Back off and retry. See Rate limits. |
500 | Unexpected server error. | Retry with exponential backoff. If persistent, contact support@thedatacity.com. |
502 | Upstream classification service unavailable. | Retry after a short delay. |
503 | Classification service temporarily unavailable (retries exhausted server-side). | Retry after a longer delay (30+ seconds). |
504 | Classification request timed out. | Retry. If the issue persists, the input may be too complex — try a shorter description. |
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
Do not auto-retry 400, 401, 402, or 422. These are client errors — the same request will fail the same way.
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.
