Error Handling

SMARTe Enrich APIs return deterministic, structured errors. Errors are evaluated early in the request lifecycle and are returned consistently across all endpoints.

Error responses are designed to be machine-readable and predictable, allowing clients to implement reliable error-handling logic.

Error Response Format

All errors use the same response structure.

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid input parameter.",
    "status": 400
  }
}

Each error response includes:

A machine-readable error code
A human-readable message
An HTTP status code

Error responses also include a smarteTransactionId in the response headers for traceability.

Common Error Categories

Errors are grouped by category to simplify handling. They can occur at different stages of request processing.

Category	HTTP Status	Description
Authentication & Authorization	401	Credential or access issues
Request Validation	400	Invalid or missing input
Credit & Usage Control	402	Insufficient credits
Rate Limiting	429	Request volume exceeded
Method Errors	405	Unsupported HTTP method
Platform Errors	500	Internal server error

Authentication & Authorization Errors

HTTP Status	Error Code	Message	Returned When	Developer Action
401	unauthorized	Authentication credentials are missing.	No API key is provided	Provide valid credentials
401	invalid_api_key	Invalid API key.	API key is invalid or malformed	Verify API key

Validation Errors

HTTP Status	Error Code	Message	Returned When	Developer Action
400	missing_identifier	At least one valid identifier must be provided.	Required identifiers missing	Provide supported identifiers
400	invalid_parameter	Invalid input parameter.	Unsupported or malformed input	Validate inputs client-side

Credit Errors

HTTP Status	Error Code	Message	Returned When	Developer Action
402	insufficient_credits	Insufficient credits to process the request.	Credit balance exhausted	Replenish credits

Rate Limiting Errors

HTTP Status	Error Code	Message	Returned When	Developer Action
429	`rate_limit_exceeded`	Too many requests. Please try again after some time.	Request exceeds allowed threshold	Retry logic with backoff

HTTP Method Errors

HTTP Status	Error Code	Message	Returned When	Developer Action
405	`method_not_allowed`	HTTP method not supported for this endpoint.	Unsupported HTTP method used	Use supported method

Platform Errors

HTTP Status	Error Code	Message	Returned When	Developer Action
500	`internal_error`	An unexpected error occurred while processing the request.	Server-side failure	Retry with backoff

💡
When contacting SMARTe Support, include:

smarteTransactionId

Timestamp

Endpoint name

Error code