Errors

Every error response uses the same envelope, with a stable, machine-readable code and the request_id of the call. The HTTP status tells you the class of problem; code tells you exactly what went wrong. The message text follows Accept-Language (pt-BR, en-US, es-ES, fr-FR, defaulting to en-US); code never changes.

{
  "error": {
    "code": "validation_failed",
    "message": "The request has invalid fields.",
    "request_id": "01J8Z3ZQ4H8K2M0T1S9P7YQF5C",
    "details": [
      { "field": "name", "code": "required", "message": "Name is required." }
    ]
  }
}

• code is the only field your integration should branch on. Handle any code you do not recognize by its HTTP status.
• details is always present. It lists the individual problems, typically on 400 and 422, and is an empty array when there is nothing to itemize. Each item carries field (request body field) or parameter (query parameter), code (the rule that was violated), and message. Business rule rejections add reason with the specific cause.
• request_id matches the X-Request-Id response header and the entry in the audit trail (GET /requests/{request_id}). Include this value when you report a problem.
• A resource outside the scope of the current credentials returns 404, exactly like a resource that does not exist. The API never confirms the existence of something you cannot see.
• The API fails closed: if the credential state, its permissions, or the rate limiter cannot be verified, the response is 503, never access.
• A validation error executes nothing and does not consume the Idempotency-Key. A 429 response does not count against the rate limit window.

Codes

What to do for each class

If a state-changing request returns 500, 503, or times out, the outcome is uncertain: retry with the same Idempotency-Key. If the first attempt was recorded, the retry returns the same response with Idempotent-Replayed: true and creates nothing new.

Report a problem

If the API behaves differently from what this documentation describes, open an API bug report. Include the operation, the request_id of the call, the account environment (production or sandbox), the request and the response without secrets, and the release from the X-Cademi-Release header. With the CLI, cademi bug --api --request-id <id> opens the same report already filled in. See Report a problem in the CLI guides.

• Questions about using the API: Discussions.
• Security vulnerabilities, including webhooks, OAuth, and event streams: report them privately at github.com/minhacademi/developers/security, never in an issue.
• Questions about your account, plan, or data: contact Cademí support.

Issues and discussions are public. Never paste an API key, a token, or data about your users.