Errors

The Martis Core API uses conventional HTTP status codes to indicate requests response statuses. Codes in the 2xx range indicate success, 4xx codes indicate client errors, and 5xx codes indicate server errors.

---

Error Response Format

Endpoints within the Martis Core API service returns an HTTP status code

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters or malformed request body
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid API key but insufficient permissions
404	Not Found	Requested resource does not exist
409	Conflict	Request conflicts with current state (e.g., duplicate idempotency key)
422	Unprocessable Entity	Request understood but cannot be processed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error; retry the request
502	Bad Gateway	Upstream service unavailable
503	Service Unavailable	Service temporarily unavailable

Error Attributes

---

Error Handling

If you experience unexpected errors, follow these steps for initial diagnosis:

• Check the status code — Use the HTTP status code to determine the error category
• Parse error messages — Extract field-specific errors from the data object for validation errors
• Implement retries — Retry requests that fail with 5xx errors using exponential backoff
• Log errors — Record error responses for debugging and monitoring
• Handle gracefully — Display user-friendly messages for common errors

Symptom	Possible Cause	Solution
All requests return 401	Invalid API key	Verify the API key is correct and not revoked
401 in production only	Environment mismatch	Ensure production API key is used with production URL
400 with empty data	Malformed JSON	Validate request body is valid JSON
409 on retry	Idempotency conflict	Generate a new idempotency key for new operations
403 after successful auth	Feature not enabled	Contact support to enable the required feature
Intermittent 5xx errors	Server issues	Implement retry logic with exponential backoff