API reference
Errors and recovery
Interpret Business API error statuses and choose a safe recovery action.
The SDK exposes typed error results. REST callers receive the same HTTP status and an error body with a code, status, and message.
| Status | Meaning | Recovery |
|---|---|---|
400 | The request failed validation. | Check required fields, enum values, ranges, and query syntax before retrying. |
401 | The key is missing or invalid. | Load the correct secret and send it in x-api-key. |
403 | The key lacks the operation's permission or the project belongs to another organization. | Use a key with the required permission from the project's organization. |
404 | The project or resource does not exist. | Verify the path IDs and stop retrying a missing resource. |
409 | The request conflicts with current state. | Refresh the resource and resolve the conflict before retrying. |
429 | The key exceeded the request budget. | Back off and retry after the rate window allows it. |
503 | The service is temporarily unavailable. | Retry with bounded exponential backoff and preserve request context. |
Inspect an SDK error
Branch on the response status
Inspect a typed validation or permission error.
import { goals } from '@orvelt/business';
const result = await goals.create({
projectId: 'PROJECT_ID',
goal: 'Learn why customers return.',
});
if (result.error) {
switch (result.response.status) {
case 401:
throw new Error('Configure a valid Business API key.');
case 403:
throw new Error('Grant the key project.goals write permission.');
default:
throw new Error(result.error.message);
}
}curl --request POST \\
--url "$ORVELT_API_BASE_URL/project/PROJECT_ID/goals" \\
--header "x-api-key: $ORVELT_BUSINESS_API_KEY" \\
--header "content-type: application/json" \\
--data '{"goal":"Learn why customers return."}'Retry only after the request changes
Do not retry validation, authentication, permission, or missing-resource errors without changing the request. See Troubleshooting for a diagnostic checklist.