Response codes

Reference for the HTTP response codes the ChartMogul API returns, what causes each one, and which are safe to retry.

The ChartMogul API uses conventional HTTP status codes to indicate the result of a request. Codes in the 2xx range mean the request succeeded, codes in the 4xx range mean something about the request needs to change, and codes in the 5xx range mean something went wrong on our side.

Error response format

Most endpoints return errors as a JSON object with code, message, and param:

{
  "code": 409,
  "message": "Another request is updating this record, please retry",
  "param": null
}

param names the request parameter responsible for the error, and is null when no single parameter is at fault.

Some endpoints use a different shape. Creating and updating customers returns errors keyed by field, as {"errors": {"<field>": "<message>"}}, and validation failures on several endpoints additionally carry an error_details array with one entry per field that failed.

Branch on the status code, not on the response body. Response bodies are not identical across all endpoints, and a request to a URL that doesn't match any endpoint returns a plain-text 404 Not Found rather than JSON.

Success status codes

Status	When you'll see it
`200 OK`	The request succeeded. Returned by all List and Retrieve endpoints, by Update endpoints, and by the endpoints that add tags or custom attributes to an existing record.
`201 Created`	A new record was created—a customer, contact, note, opportunity, task, or data source.
`202 Accepted`	The request was accepted and is being processed asynchronously. Returned by all delete endpoints, as well as customer merges and unmerges and subscription connects and disconnects. The change may not be visible if you read the record immediately afterward.
`304 Not Modified`	An update request for an opportunity or a task contained no updatable fields. Nothing was changed. The response has no body.

Error status codes

Status	What it means	Example message
`400 Bad Request`	The request couldn't be parsed, or a parameter failed validation. Common causes are a missing or invalid parameter, a malformed JSON body, an invalid pagination cursor, a `start-date` later than the `end-date`, an empty tag name, or referencing a custom attribute that doesn't exist.	`Parameter "customer_uuid" is missing`
`401 Unauthorized`	The API key is missing, malformed, unknown, or no longer active. Authentication is checked before the request body is parsed, so an invalid key returns `401` even when the request is malformed in other ways too.	`Invalid API key provided`
`403 Forbidden`	The key isn't allowed to make this request: a read-only API key was used for a write request, the account no longer has API access, or the user behind the key lacks the required permission.	`Invalid API key with write access provided`
`404 Not Found`	Either the URL doesn't match any endpoint, or a record the request refers to doesn't exist. This can be a customer, contact, note, subscription, opportunity, task, data source, or the email address of an owner or assignee.	`Contact(s) could not be found.`
`405 Method Not Allowed`	The URL exists but doesn't accept this HTTP method. The response carries an `Allow` header listing the methods it does accept.	`405 Not Allowed`
`406 Not Acceptable`	A response format other than JSON was requested. The API only returns JSON.	`The requested format 'xml' is not supported.`
`409 Conflict`	Another request is updating the same record and didn't release its database lock in time. This is transient. Retry the request. It's most likely when several write requests target the same record in parallel, for example when creating several contacts for one customer at once.	`Another request is updating this record, please retry`
`415 Unsupported Media Type`	The request body was sent with a `Content-Type` other than `application/json`, or the request wasn't encoded as UTF-8.	`Request was not encoded correctly. All requests should be encoded with UTF-8`
`422 Unprocessable Content`	The request was understood, but the record couldn't be saved. Common causes are an `external_id` that is already taken, a custom attribute value that doesn't match its type or is too long, or an owner or assignee who is inactive. Inspect `error_details` for the field-level reasons.	Varies by field. See `error_details`
`429 Too Many Requests`	A rate limit was exceeded, or the database is temporarily read-only while we perform maintenance.	`Your request rate has exceeded our rate limit.`
`500 Internal Server Error`	Something went wrong on our side.	`Something went wrong`
`503 Service Unavailable`	Your account is temporarily in a read-only state, or too many parallel connections were opened. See rate limits.	`Ongoing maintenance, please retry later`

Retrying failed requests

409, 429, and 503 are transient. Retry them with exponential backoff.

A 500 can be retried once or twice. If a write request fails with a 500, the change may or may not have been applied, so re-read the record before retrying rather than blindly repeating the write. If it persists, contact support.

Don't retry 400, 401, 403, 404, 405, 406, 415, or 422 unchanged—the request itself has to change first.

Exponential backoff. Our client libraries implement exponential backoff. See rate limits for the details and for links to each library's documentation.