Error handling

Response shape (reference)

Many Gateway errors return a simple string message:

{
  "error": "quota exhausted"
}

Structured validation errors may evolve toward:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "data_url is required",
    "details": {
      "field": "data_url",
      "constraint": "required"
    }
  }
}

Implement clients to read error as either a string or an object with code / message for forward compatibility.

HTTP status reference

HTTP Status	Code	Meaning
400	VALIDATION_ERROR	Body failed validation (label_spec, URL format, batch size, etc.)
401	UNAUTHORIZED	Missing / invalid API key
403	FORBIDDEN	Valid key but quota exhausted or disallowed
404	NOT_FOUND	Task, job, webhook, or customer not found for this tenant
409	CONFLICT	Duplicate email at registration; job export before completion
429	RATE_LIMITED	Too many requests — backoff using Retry-After
500	INTERNAL_ERROR	Server-side failure — retry with backoff

Examples

400:

{
  "error": "unsupported task type"
}

401:

{
  "error": "invalid API key"
}

404:

{
  "error": "task not found"
}

409 (registration):

{
  "error": "email already registered"
}

429:

{
  "error": "rate limit exceeded"
}

tip

Log X-Request-Id (if provided by your proxy) or the response body on 5xx when opening support tickets.