Error Handling

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

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

Error Response Format

All errors follow a consistent JSON 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 response headers for traceability.

HTTP Status Codes

Status Code	Description
200	Request successful, data returned
204	Request successful, no data found
400	Invalid request or input parameters
401	Authentication failure
404	Resource or endpoint not found
409	Request conflict or invalid state
429	Rate limit exceeded
500	Internal server error

Common Error Categories

Authentication Errors

HTTP Status	Error Code	Message	When It Occurs	Developer Action
401	AUTH_INVALID	Authentication credentials are missing or invalid.	Missing or invalid API key	Provide valid credentials

Validation Errors

HTTP Status	Error Code	Message	When It Occurs	Developer Action
400	invalid_parameter	Invalid input parameter.	Invalid filters or malformed input	Validate request parameters

Rate Limiting Errors

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

Server Errors

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

Debugging and Support

When troubleshooting issues:

Review the error code and message carefully
Verify request payload and filters
Check authentication credentials
Use the smarteTransactionId for tracing

When contacting SMARTe Support, include:

smarteTransactionId
Timestamp
Endpoint
Error details