Errors

How the API returns and structures errors

Overview

Our API uses standard HTTP status codes to indicate whether a request was successful or failed. While HTTP codes provide a high-level summary, we also return a structured JSON error object with descriptive fields so you can programmatically detect, log, and handle specific error cases.

In general:

• 2xx — The request succeeded.
• 4xx — The request failed due to a problem with the information provided (e.g., missing a required parameter, invalid value, business rule violation).
• 5xx — A problem occurred on our servers or with an upstream dependency (rare).

Error Response Format

When an error occurs, the response body includes a JSON object containing details about the error:

Field	Type	Description
type	string	A short string classifying the error. Possible values: api_error, validation_error, auth_error, idempotency_error, rate_limit_error.
code	string (nullable)	A programmatic code identifying the specific error.
message	string (nullable)	A human-readable message explaining the error. Suitable for displaying to users where appropriate.
param	string (nullable)	The parameter related to the error, if applicable.
doc_url	string (nullable)	A link to relevant documentation for this error type.
request_id	string (nullable)	An internal request identifier for troubleshooting with support.

Example

{
  "error": {
    "type": "validation_error",
    "code": "missing_required_field",
    "message": "The 'amount' field is required.",
    "param": "amount",
    "doc_url": "https://docs.mansa.io/errors/missing_required_field",
    "request_id": "req_123456789"
  }
}

HTTP Status Code Summary

Code	Meaning	Notes
200 OK	Success	Everything worked as expected.
400 Bad Request	Invalid request	Missing or invalid parameters.
401 Unauthorized	Authentication error	No valid API key or token provided.
403 Forbidden	Permission error	API key lacks required permissions.
404 Not Found	Resource not found	The requested resource does not exist.
409 Conflict	Request conflict	Likely due to duplicate or conflicting data.
422 Unprocessable Entity	Validation error	Request parameters are syntactically correct but semantically invalid.
429 Too Many Requests	Rate limit exceeded	Slow down and retry with exponential backoff.
500 Internal Server Error	Server error	Something went wrong on our end.
502 Bad Gateway	Upstream service error	Temporary issue with dependencies.
503 Service Unavailable	Temporary outage	Try again later.
504 Gateway Timeout	Timeout	Upstream service took too long to respond.

Error Types

Type	Description
api_error	Catch-all for unexpected server errors.
validation_error	Invalid request parameters or data.
auth_error	Missing or invalid authentication credentials.
idempotency_error	Idempotency key reused with mismatched request data.
rate_limit_error	Request rate exceeded the allowed limit.

Best Practices for Handling Errors

• Log the full error object for troubleshooting.
• Handle 4xx errors programmatically where possible (e.g., show the message to the user if it’s safe to do so).
• Implement retries with exponential backoff for 5xx or 429 errors.
• Use param to highlight specific fields in form validation errors.
• Monitor error rates to detect systemic issues early.

---

Related guide: Error Handling