Responses & errors
Read failures consistently and choose the right next step.
Successful single-resource responses use { "data": ... }. Company creation also returns created. Lists use { "data": [...], "page": ... } with bounded pagination.
Error shape
{
"error": "Invalid request data.",
"code": "validation_error",
"details": [{ "field": "due_date", "message": "Invalid ISO datetime" }]
}Use code and the HTTP status in your integration. error and validation messages are human-readable and can change. details is present for validation failures. Responses carry X-Request-Id; retain it with the method, path, timestamp and status when troubleshooting. Never log your Authorization header.
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 200 | Read, update, or an already-existing company | Use the returned data |
| 201 | A record was created | Save its ID |
| 400 | validation_error or invalid_json | Fix the JSON, fields or parameter format |
| 401 | unauthorized | Check the Bearer header and whether the key was removed |
| 403 | insufficient_permissions | Grant the resource permission shown in the error |
| 404 | not_found | Check the path/ID and that the record is in this workspace |
| 409 | conflict or company_deleted | Verify the existing record, or restore the company in Aventra |
| 413 | payload_too_large | Keep the JSON body at or below 100 KB |
| 415 | unsupported_media_type | Send uncompressed JSON with Content-Type: application/json |
| 422 | invalid_assignee, invalid_reference or company_unavailable | Check the linked company or workspace member |
| 429 | rate_limited | Wait for Retry-After before retrying |
| 500 | internal_error | Check the outcome, then follow retry guidance |
| 503 | temporarily_unavailable | Wait for Retry-After before retrying |
A linked company or contact from another workspace is treated as not found. An assignee outside your workspace is rejected. The API does not disclose other customers' data.
Missing records
A missing or deleted record returns 404. Filtered directory lookups return 200 with an empty data array when no user matches the email address.
Common mistakes
- Using
app.aventra.no/api/v1instead ofapi.aventra.no/api/v1. - Passing an organisation number as
company_id, which requires a UUID. - Sending
customer_id,tenant_id, or other unknown fields in a write body. - Sending a date without a timezone, or using øre for an offer amount.
- Retrying a note or relationship request without checking whether it succeeded.