Responses & errors
Handle Aventra CRM API responses and errors, from validation and permissions to rate limits, missing records and retry decisions.
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.
Reliable integrations
Build reliable Aventra CRM integrations with saved UUIDs, recovery checks and bounded retries. Handle timeouts without duplicating records.
Find workspace users
Find Aventra workspace users by email or browse the directory. Use their UUIDs to assign CRM tasks, company records and sales offers.