Error handling

When you send a request to the API, things don't always go as expected. You might have a typo in the URL, use invalid credentials, or send a malformed request body. When something goes wrong, the API responds with an error response instead of the data you asked for.

Error handling is how your code detects and reacts to these error responses. Instead of crashing or silently failing, a well-built integration checks for errors and takes appropriate action — such as retrying the request, logging the problem, or notifying the user.

Error response format

Every error response from the Medipim API is a JSON object with the following structure:

{
    "error": {
        "status": 401,
        "code": "authentication.not_authenticated",
        "message": "A human-readable description of what went wrong."
    }
}

• status — the HTTP status code (e.g. 401, 404, 422). This tells you the general category of the problem. While this field is included in the response body for convenience, you should always use the actual HTTP status code from the response itself (i.e. the status line, not the JSON body) to determine how to handle the error. The HTTP status is the standard, reliable way to detect errors — every HTTP client gives you access to it, and it works even when the response body is empty or malformed.
• code — a Medipim-specific error code (e.g. authentication.not_authenticated). This is more precise than the status code and tells you exactly what went wrong. The same HTTP status can have different error codes depending on the cause.
• message — a human-readable description of the error.

For validation errors (422), the response also includes a violations array with details about which fields failed validation.

Error codes

The table below lists the error codes you may encounter. Note that a single HTTP status code can have multiple possible error codes — check the code field to determine the exact cause.

400 — Bad request

Error code	Description
bad_request	The request body or parameters are invalid. Check that your JSON is well-formed and that required fields are present.

401 — Unauthorized

Error code	Description
authentication.not_authenticated	The request has no valid authentication credentials. Make sure you are sending a correct Authorization header (see Authentication).
authentication.api_key_not_found	The API key you provided does not exist. Double-check that you are using the correct key.
authentication.invalid_api_secret	The API secret does not match the key. Verify that you are using the correct key and secret pair.
authentication.api_key_is_not_active	The API key exists but has been deactivated. Contact info@medipim.com to reactivate it.

403 — Forbidden

Error code	Description
not_authorized	Your credentials are valid, but you don't have permission to perform this action. Verify that your API key has the necessary permissions.

404 — Not found

Error code	Description
not_found	The requested resource does not exist (e.g. a product ID that doesn't match any product).
endpoint_not_found	The API endpoint URL does not exist. Check for typos in the URL path.

405 — Method not allowed

Error code	Description
http_method_not_allowed	The HTTP method you used (e.g. GET) is not supported for this endpoint. The error message will tell you which methods are allowed.

422 — Validation failed

Error code	Description
validation_failed	The request was understood but contains invalid data. The response includes a violations array with details about which fields failed and why.

429 — Too many requests

Error code	Description
too_many_requests	You have exceeded the rate limit. Back off and retry after a short delay. See Throttling & quotas for details.

500 — Server error

Error code	Description
server_error	The server encountered an unexpected error. If this persists, contact support.