Error Codes

Every error response follows the same envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "n_samples must be > 0",
    "doc_url": "https://docs.dataxid.com/docs/errors#parameter_invalid",
    "param": "n_samples"
  },
  "request_id": "req_abc123"
}

Field	Type	Description
`type`	`string`	Error category (see Error Types)
`code`	`string`	Machine-readable error code (unique, stable)
`message`	`string`	Human-readable description
`doc_url`	`string`	Link to this page for the specific error code
`param`	`string`	Which parameter caused the error (when applicable)
`request_id`	`string`	Include this in support requests

Error Types

Type	Description
`authentication_error`	API key missing or invalid
`invalid_request_error`	Bad parameters, wrong model state, or idempotency conflict
`not_found_error`	Resource does not exist (or belongs to another org)
`rate_limit_error`	Too many requests
`quota_exceeded_error`	Monthly usage quota exceeded
`api_error`	Server-side error (infrastructure issue, unexpected failure)

Error Code Reference

api_key_missing


HTTP Status	`401 Unauthorized`
Type	`authentication_error`
When	Request to `/v1/*` without an `Authorization` header

Example response:

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_missing",
    "message": "Authorization header with Bearer token is required.",
    "doc_url": "https://docs.dataxid.com/docs/errors#api_key_missing"
  },
  "request_id": "req_abc123"
}

How to fix: Add the Authorization: Bearer <api_key> header to your request.

api_key_invalid


HTTP Status	`401 Unauthorized`
Type	`authentication_error`
When	The provided API key does not match any known key

How to fix:

Verify the key is correct (no trailing spaces, no truncation)
Check the key prefix: dx_test_ for sandbox, dx_live_ for production
If the key was revoked, generate a new one

parameter_invalid


HTTP Status	`400 Bad Request`
Type	`invalid_request_error`
When	Request body fails validation (missing required field, wrong type, out of range)

Example response:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Value error, ensure this value is greater than 0",
    "doc_url": "https://docs.dataxid.com/docs/errors#parameter_invalid",
    "param": "body.config.batch_size"
  },
  "request_id": "req_abc123"
}

How to fix: Check the param field to identify which parameter is invalid. Refer to the API Reference for valid values.

model_not_found


HTTP Status	`404 Not Found`
Type	`not_found_error`
When	The model ID does not exist, or belongs to a different organization

How to fix:

Verify the model ID (format: mdl_<12 hex chars>)
The model may have been deleted

Security: Cross-organization resources always return 404 — not 403 — to prevent information leakage.

model_not_ready


HTTP Status	`400 Bad Request`
Type	`invalid_request_error`
When	Operation requires `training` or `ready` status, but model is in `created`, `building`, or `failed` state

Example response:

{
  "error": {
    "type": "invalid_request_error",
    "code": "model_not_ready",
    "message": "Model mdl_a1b2c3d4e5f6 is in 'created' state, cannot generate",
    "doc_url": "https://docs.dataxid.com/docs/errors#model_not_ready"
  },
  "request_id": "req_abc123"
}

How to fix:

Check model status with GET /v1/models/{id}
Wait for training to complete (status → training → ready)
If status is failed, check the error field and create a new model

training_service_unavailable


HTTP Status	`503 Service Unavailable`
Type	`api_error`
When	Training infrastructure is temporarily unavailable (scaling, maintenance)

How to fix:

Retry after a few seconds — infrastructure auto-scales and may need warm-up time
The SDK retries 5xx errors automatically with exponential backoff
If persistent, contact support with the request_id

idempotency_key_in_use


HTTP Status	`409 Conflict`
Type	`invalid_request_error`
When	A concurrent request with the same `Idempotency-Key` is still being processed

How to fix:

Wait for the original request to complete, then retry with the same key (you'll get the cached response)
If you want a new request, use a different Idempotency-Key
Keys expire after 24 hours

quota_exceeded


HTTP Status	`402 Payment Required`
Type	`quota_exceeded_error`
When	Organization exceeded the monthly usage quota (free tier: 100K rows/month)

Example response:

{
  "error": {
    "type": "quota_exceeded_error",
    "code": "quota_exceeded",
    "message": "Monthly row quota exceeded. Upgrade your plan for additional capacity.",
    "doc_url": "https://docs.dataxid.com/docs/errors#quota_exceeded"
  },
  "request_id": "req_abc123"
}

How to fix:

Check your current usage at app.dataxid.com
Upgrade your plan for additional capacity
Usage resets at the beginning of each billing period

rate_limit_exceeded


HTTP Status	`429 Too Many Requests`
Type	`rate_limit_error`
When	Organization exceeded the request rate limit (default: 60 requests/minute)

Example response:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "doc_url": "https://docs.dataxid.com/docs/errors#rate_limit_exceeded"
  },
  "request_id": "req_abc123"
}

Response headers:

Header	Example	Description
`X-RateLimit-Limit`	`60`	Requests allowed per window
`X-RateLimit-Remaining`	`0`	Requests remaining
`X-RateLimit-Reset`	`1708425060`	Unix epoch when window resets
`Retry-After`	`12`	Seconds to wait before retrying

How to fix:

Wait for the Retry-After duration, then retry
The SDK handles this automatically with exponential backoff
Rate limits are per organization, not per API key

internal_error


HTTP Status	`500 Internal Server Error`
Type	`api_error`
When	Unexpected server error

How to fix:

Retry the request — transient errors often resolve on retry
The SDK retries 5xx errors automatically
If persistent, contact support with the request_id
In non-debug mode, the error message is generic for security

SDK Exception Mapping

The Python SDK maps API error codes to typed exceptions. Use these for structured error handling:

Error Code	SDK Exception	Description
`api_key_missing`	`dataxid.AuthenticationError`	Missing API key
`api_key_invalid`	`dataxid.AuthenticationError`	Invalid API key
`parameter_invalid`	`dataxid.InvalidRequestError`	Bad request parameters
`model_not_found`	`dataxid.NotFoundError`	Model does not exist
`model_not_ready`	`dataxid.ModelNotReadyError`	Model not in correct state
`quota_exceeded`	`dataxid.QuotaExceededError`	Usage quota exceeded
`rate_limit_exceeded`	`dataxid.RateLimitError`	Too many requests
`idempotency_key_in_use`	`dataxid.ConflictError`	Duplicate request in progress
`training_service_unavailable`	`dataxid.APIError`	Infrastructure unavailable
`internal_error`	`dataxid.APIError`	Unexpected server error

All exceptions inherit from dataxid.DataxidError:

import dataxid

try:
    synthetic = dataxid.synthesize(data=df)
except dataxid.AuthenticationError:
    print("Invalid API key")
except dataxid.QuotaExceededError as e:
    print(f"Quota exceeded. Upgrade: {e.upgrade_url}")
except dataxid.RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}s")
except dataxid.DataxidError as e:
    print(f"Error: {e}")

On this page