Errors

Every error answer is application/problem+json following RFC 9457. The code is the contract, type points at its page in this portal.

Anatomy of an error answer

Branch on code in your client, never on the text. Quote the requestId in support requests.

POST /v1/contacts

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en
Request-Id: req_01JBA7Q2M4X9C3T8V5N6K1W0PZ

{
  "type": "https://developers.bodo-app.com/problems/VALIDATION_FAILED",
  "title": "Validation failed",
  "status": 422,
  "detail": "A field has an invalid value.",
  "instance": "/v1/contacts",
  "code": "VALIDATION_FAILED",
  "requestId": "req_01JBA7Q2M4X9C3T8V5N6K1W0PZ",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Not a valid email address."
    }
  ]
}

title and detail come in German and English, following Accept-Language. More under Language.

Codes

Every answer carries Request-Id in the header and requestId in the body, for 401, 429 and 500 too.

Situation	Status · code
Input	400 INVALID_REQUEST · 422 VALIDATION_FAILED
Key invalid, expired, revoked, paused, IP not allowed, API of the organization off	401 UNAUTHENTICATED
Permission or scope missing, organization closed or scheduled for deletion	403 FORBIDDEN
Organization header does not match the key	403 ORGANIZATION_MISMATCH
Public API module not enabled for the organization, for OAuth tokens too	403 API_MODULE_DISABLED
Family blocked, such as deleting, finalizing or sending an invoice	403 RISK_FAMILY_BLOCKED
Object invisible or unknown	404 NOT_FOUND
Operation not in the version or without the preview header	404 OPERATION_NOT_IN_VERSION
Idempotency	409 IDEMPOTENCY_IN_PROGRESS · 422 IDEMPOTENCY_PAYLOAD_MISMATCH
Version switched off	410 VERSION_SUNSET
Precondition	412 PRECONDITION_FAILED · 428 PRECONDITION_REQUIRED
Lists and parameters	400 CURSOR_MISMATCH · 400 UNKNOWN_PARAMETER
Files	409 UPLOAD_INCOMPLETE · 422 UPLOAD_CHECKSUM_MISMATCH · 422 UPLOAD_REJECTED
Batch	400 BATCH_TOO_LARGE · 422 BATCH_FAMILY_NOT_ALLOWED
Webhooks	422 WEBHOOK_URL_INVALID · 409 WEBHOOK_ENDPOINT_LIMIT_REACHED
Throttling	429 RATE_LIMITED · 429 OVERLOADED · 429 QUOTA_EXHAUSTED
API paused by the operator (emergency stop)	503 API_PAUSED
Service behind	502 UPSTREAM · 503 INSTANCE_PENDING · 500 INTERNAL

Every credential reason gives the same 401 without detail. The owner sees the exact reason in the request log in Bodo. All codes with their pages: Problem types.

403 API_MODULE_DISABLED during the preview

The door checks the module publicApi of the organization first, then the API level the organization chooses itself.

Answer by module publicApi and API level of the organization
Module publicApi	API level of the organization: off	API level of the organization: read	API level of the organization: on
Module publicApi: off	403API_MODULE_DISABLEDmodule first, level does not matter	403API_MODULE_DISABLEDmodule first, level does not matter	403API_MODULE_DISABLEDmodule first, level does not matter
Module publicApi: on	401UNAUTHENTICATEDlike any invalid key	403FORBIDDENonly for writes, reads go through	2xxcall goes through

While the module is off, keys, subscriptions and tokens rest. Nothing is deleted, and everything continues once it is switched on again. Events from the time it was off are not delivered later; syncing with updatedSince still works.

Answer in German

Example response

GET /v1/contacts

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: de

{
  "type": "https://developers.bodo-app.com/problems/API_MODULE_DISABLED",
  "title": "Öffentliche API nicht freigeschaltet",
  "status": 403,
  "detail": "Für diese Organisation ist das Modul Öffentliche API nicht freigeschaltet. Dein Bodo-Ansprechpartner schaltet es frei.",
  "code": "API_MODULE_DISABLED",
  "requestId": "req_01JBF2K8N3Q7R5T9V1X4Z6B0CD"
}

Answer in English

Example response

GET /v1/contacts · Accept-Language: en

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://developers.bodo-app.com/problems/API_MODULE_DISABLED",
  "title": "Public API not enabled",
  "status": 403,
  "detail": "The Public API module is not enabled for this organization. Your Bodo contact can enable it.",
  "code": "API_MODULE_DISABLED",
  "requestId": "req_01JBG3L9P4R8S6U0W2Y5A7C1DE"
}