Error Responses

Custodian Labs APIs return standard HTTP status codes with a JSON error body.

Use this page to understand common error responses and how to troubleshoot them.

Error Shape

Most errors follow this shape:

{
  "error": "Invalid API key",
  "status_code": 401,
  "code": "http_error"
}

Validation errors include request details:

{
  "error": "Request validation failed",
  "status_code": 422,
  "code": "request_validation_error",
  "details": []
}

Some usage-limit errors include additional quota fields.

Common Status Codes

Status	Meaning	Common causes
400	Bad request	Missing file, unsupported file extension, invalid document.
401	Unauthorized	Missing, invalid, or inactive API key.
403	Forbidden	Expired key or key cannot be used for the request.
422	Validation error	Invalid JSON body, missing required field, unsupported enum value.
429	Usage limit reached	Token credits or request limit reached.
500	Server error	Required server dependency is unavailable or an internal error occurred.
503	Service unavailable	API key validation or backend dependency is temporarily unavailable.

Authentication Errors

Missing API key:

{
  "error": "Missing X-API-Key header",
  "status_code": 401,
  "code": "http_error"
}

Invalid API key:

{
  "error": "Invalid API key",
  "status_code": 401,
  "code": "http_error"
}

Usage Limit Errors

When the API key does not have enough credits for the request, the response may include quota details:

{
  "error": "Not enough token credits remaining for this request",
  "status_code": 429,
  "code": "not_enough_credits",
  "token_limit": 50000,
  "tokens_used": 49950,
  "required_tokens": 200,
  "remaining_credits": 50
}

When the request limit is reached:

{
  "error": "API request limit reached",
  "status_code": 429,
  "code": "request_limit_reached",
  "request_limit": 500,
  "requests_used": 500
}

Validation Errors

Validation errors usually mean the request body does not match the endpoint schema.

Common examples:

• Missing text.
• Invalid masking_type.
• Invalid domain.
• pca_dimension outside the supported range.
• Wrong content type for file upload.

File Errors

File endpoints may return 400 when the uploaded file does not match the endpoint.

Error case	Fix
.doc sent to the DOCX endpoint	Convert the file to .docx.
Non-PDF sent to the PDF endpoint	Upload a .pdf file.
Unsupported spreadsheet extension	Use .csv, .xlsx, or .xls.
Empty file upload	Upload a file with content.

Troubleshooting Checklist

1. Confirm the X-API-Key header is present.
2. Confirm the key is copied correctly from the Dashboard.
3. Confirm the request uses the right endpoint.
4. Confirm the request body or form fields match the endpoint.
5. Check usage and request limits in the Dashboard.
6. Retry later if the error is 500 or 503.

Related Pages

• Authentication
• Text Endpoints
• File Endpoints