Skip to main content

​
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:
FieldTypeDescription
typestringA short string classifying the error. Possible values: api_error, validation_error, auth_error, idempotency_error, rate_limit_error.
codestring (nullable)A programmatic code identifying the specific error.
messagestring (nullable)A human-readable message explaining the error. Suitable for displaying to users where appropriate.
paramstring (nullable)The parameter related to the error, if applicable.
doc_urlstring (nullable)A link to relevant documentation for this error type.
request_idstring (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

CodeMeaningNotes
200 OKSuccessEverything worked as expected.
400 Bad RequestInvalid requestMissing or invalid parameters.
401 UnauthorizedAuthentication errorNo valid API key or token provided.
403 ForbiddenPermission errorAPI key lacks required permissions.
404 Not FoundResource not foundThe requested resource does not exist.
409 ConflictRequest conflictLikely due to duplicate or conflicting data.
422 Unprocessable EntityValidation errorRequest parameters are syntactically correct but semantically invalid.
429 Too Many RequestsRate limit exceededSlow down and retry with exponential backoff.
500 Internal Server ErrorServer errorSomething went wrong on our end.
502 Bad GatewayUpstream service errorTemporary issue with dependencies.
503 Service UnavailableTemporary outageTry again later.
504 Gateway TimeoutTimeoutUpstream service took too long to respond.

​
Error Types

TypeDescription
api_errorCatch-all for unexpected server errors.
validation_errorInvalid request parameters or data.
auth_errorMissing or invalid authentication credentials.
idempotency_errorIdempotency key reused with mismatched request data.
rate_limit_errorRequest 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