Errors

When integrating with the Mambo API, understanding error handling is essential for developing robust applications. This guide explains the types of errors you might encounter, how to interpret them, and best practices for handling them in your code.

Responses

Mambo API error responses can be broken down into three types:

• General errors: are the bulk of the error types returned by the API. They include an object not found all the way to an unexpected server error.
• Validation errors: are the most common type of error, and are raised by invalid request data or parameters.
• OAuth2 errors: are raised when there is an error during API authentication.

General error example

JSON

{
  "error": {
      "type": "KeyNotFoundException",
      "message": "Could not find a behaviour with the ID [676ac53391520fcbcb6b4b20]"
  }
}

Validation error example

JSON

{
  "error": {
      "type": "ValidationException",
      "message": "A validation error occurred. Please check the fields for errors.",
      "params": [
          {
              "name": "expiration.period.months",
              "message": "The months must be empty when using the weeksOfYear criteria."
          }
      ]
  }
}

OAuth2 error example

In order to conform to the OAuth 2 specification, the response below is not wrapped in an error property and uses snake case for the property names. The type information is added in order to align with the standard Mambo error responses.

Note: the invalid_token error will be returned using the old error format on versions prior to 8.0.0.

JSON

{
  "type": "OAuth2Exception",
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons.",
  "error_uri": "https://datatracker.ietf.org/doc/html/rfc6750#section-3.1"
}

HTTP status codes

Mambo uses standard HTTP status codes to indicate the success or failure of a request.

More information on HTTP status codes can be found in the specifications.

Status code	Name	Description
200	OK	Success!
400	Bad request	The request is invalid. This is the status used when returning ValidationExceptions and other exceptions related to incorrectly formed requests.
401	Unauthorised	There was a problem authenticating the request. Check that the OAuth signature is being correctly applied and / or that your API keys are correct.
403	Forbidden	The request is understood but has been refused by the API. This is normally associated to a lack of permissions.
404	Not found	The URI requested is invalid or the resource requested, such as a user, does not exist.
405	Method not allowed	The method specified is not allowed for the URI requested e.g. using POST on a GET resource.
406	Not acceptable	The accept headers specify a format that is not supported by the URI resource requested.
409	Conflict	The request could not be completed due to a conflict with the current state of the resource. For example, duplicate user UUIDs could generate this status code.
415	Unsupported media type	The server is refusing to service the request because the entity of the request is in a format not supported by the requested URI resource for the requested method.
429	Too many requests	The user has sent too many requests in a given amount of time.
500	Internal server error	Oops! Something broke down. Please get in touch and let us know if you come across this and we'll get our engineers to investigate immediately.
503	Service unavailable	The API is running but appears to be overloaded and can't complete your response.

Error types

In addition to the status codes above, every error response will contain the type of error. The most common error types are grouped below for easier reference. For API specific errors, please see the API Explorer.

Validation and request (400)

Type	Description
ValidationException	The request is invalid or has invalid parameters.
BadRequestException	The request is invalid for reasons other than validation.
ImpossibleDeleteException	The requested resource cannot be deleted due to dependencies.
InvalidIdempotencyKeyException	The format of the idempotency key is not valid.
ImageException	There was a problem processing the image.
VersionException	There was a problem processing the request's version information.
VersionParseException	There was a problem parsing the request's version number.

Authentication (401, 403)

Type	Description	Status code
OAuth2Exception	There was a problem with the OAuth2 authentication flow. Check the error code and description for more information.	400 / 401 / 403
UnauthorizedException	The request cannot be authenticated and is not a standard OAuth2 error.	401
ForbiddenException	The request is understood but has been refused usually due to a lack of permissions.	403

Resource (404)

Type	Description
KeyNotFoundException	The requested resource could not be found.
UserNotFoundException	The requested user could not be found.
TagNotFoundException	The requested tag could not be found.
ApiNotFoundException	The requested API endpoint could not be found.

Method and format (405, 406, 415)

Type	Description	Status code
MethodNotAllowedException	The method specified is not allowed for the URI requested e.g. using POST on a GET resource.	405
NotAcceptableException	The accept headers specify a format that is not supported by the resource requested.	406
UnknownMediaTypeException	The media type (e.g. XML) is not supported by the resource requested.	415

Conflict (409)

Type	Description
DuplicateException	The resource you are trying to save already exists. For example, trying to save two users with the same UUID.
IdempotencyKeyAlreadyUsedException	The idempotency key was previously used with different API, body or query parameters.
IdempotencyRequestInProgressException	A request with the same idempotency key is already in progress.

Server (500, 503)

Type	Description	Status code
InternalServerException	The server encountered an unidentified error processing the request.	500
PersistenceException	The database service has a problem and can't complete your request.	503
StorageException	The storage service has a problem and can't complete your request.	503
ServiceUnavailableException	The server or dependent service is overloaded and can't complete your request.	503

SDK error handling

When working with the Mambo SDK, you should implement appropriate error handling to gracefully manage different error scenarios. The code sample below shows you how to handle exceptions using the different SDKs.

Java

.NET

PHP

try {
// Make a request using the Mambo SDK
} catch( InvalidTokenException ex ) { 
// Token expired or is invalid - refresh and retry 
} catch( AuthenticationException ex ) {
// Invalid credentials or unauthorized access
} catch( IdempotencyException ex ) { 
// Duplicate request detected
} catch ( JsonProcessingException ex ) {
// Failed to parse API response
} catch( ApiConnectionException ex ) { 
// Network or connectivity error
} catch( MamboApiException ex ) { 
// API returned an error response
} catch( MamboException ex ) { 
// Generic SDK error occurred
} catch( Exception ex ) {
// Unexpected error occurred
}

try {
// Make a request using the Mambo SDK
} catch( InvalidTokenException ex ) { 
// Token expired or is invalid - refresh and retry 
} catch( AuthenticationException ex ) {
// Invalid credentials or unauthorized access
} catch( IdempotencyException ex ) { 
// Duplicate request detected
} catch ( JsonProcessingException ex ) {
// Failed to parse API response
} catch( ApiConnectionException ex ) { 
// Network or connectivity error
} catch( MamboApiException ex ) { 
// API returned an error response
} catch( MamboException ex ) { 
// Generic SDK error occurred
} catch( Exception ex ) {
// Unexpected error occurred
}

try {
// Make a request using the Mambo SDK
} catch( InvalidTokenException $ex ) { 
// Token expired or is invalid - refresh and retry 
} catch( AuthenticationException $ex ) {
// Invalid credentials or unauthorized access
} catch( IdempotencyException $ex ) { 
// Duplicate request detected
} catch ( JsonProcessingException $ex ) {
// Failed to parse API response
} catch( ApiConnectionException $ex ) { 
// Network or connectivity error
} catch( MamboApiException $ex ) { 
// API returned an error response
} catch( MamboException $ex ) { 
// Generic SDK error occurred
} catch( Exception ex ) {
// Unexpected error occurred
}

Troubleshooting tips

When dealing with API errors, consider the following:

1. For authentication errors, verify your API keys and OAuth implementation
2. For validation errors, carefully review the params array for specific field issues
3. For 429 errors, implement backoff strategies and respect rate limits
4. For 5xx errors, implement retry logic with exponential backoff

---

Related topics

• API keys
• Authentication