Error Handling
The API uses standard HTTP status codes and returns detailed error information in a consistent format.
All errors return a JSON object with the following structure:
{
"error": {
"code": "error_code",
"message": "Human-readable error message",
"request_id": "req_abc123def456",
"details": {}
}
}
Save the request_id from error responses. When contacting support, include this ID for faster troubleshooting.
HTTP Status Codes
| Status | Description |
|---|
| 200 | Success |
| 201 | Created - Resource successfully created |
| 400 | Bad Request - Invalid parameters or validation failed |
| 401 | Unauthorized - Invalid, missing, or expired API key |
| 403 | Forbidden - Insufficient permissions or scope |
| 404 | Not Found - Requested resource doesn’t exist |
| 429 | Too Many Requests - Rate limit exceeded (see Rate Limits) |
| 500 | Internal Server Error - Unexpected server error |
Error Codes Reference
Authentication Errors (401)
| Code | Description |
|---|
missing_api_key | No API key provided in the Authorization header |
invalid_auth_format | Authorization header not using Bearer scheme |
invalid_api_key | API key format is invalid or key doesn’t exist |
api_key_revoked | API key has been revoked |
api_key_expired | API key has expired |
organization_not_found | Organization associated with API key no longer exists |
OAuth Errors (401/403)
| Code | Description |
|---|
oauth_invalid_token | OAuth access token is invalid, expired, or revoked |
oauth_insufficient_scope | Token doesn’t have required scopes for this endpoint |
Device Auth Errors (400)
| Code | Description |
|---|
authorization_pending | User hasn’t approved/denied yet (keep polling) |
slow_down | Polling too fast. Increase interval by 5 seconds |
access_denied | User denied the authorization request |
expired_token | Device code has expired. Start a new flow |
Validation Errors (400)
| Code | Description |
|---|
validation_error | Request body failed validation. Check details.issues |
invalid_request | Request format is invalid |
Server Errors (500)
| Code | Description |
|---|
internal_error | Unexpected server error |
Handling Errors
JavaScript/TypeScript
try {
const response = await fetch('https://api.v2.dealmachine.com/v1/account', {
headers: {
'Authorization': `Bearer ${apiKey}`,
},
});
if (!response.ok) {
const { error } = await response.json();
switch (error.code) {
case 'invalid_api_key':
console.error('Check your API key');
break;
case 'validation_error':
console.error('Validation issues:', error.details?.issues);
break;
default:
console.error('Error:', error.message);
}
return;
}
const data = await response.json();
} catch (err) {
console.error('Network error:', err);
}
Python
import requests
response = requests.get(
'https://api.v2.dealmachine.com/v1/account',
headers={'Authorization': f'Bearer {api_key}'}
)
if not response.ok:
error = response.json()['error']
if error['code'] == 'invalid_api_key':
print('Check your API key')
elif error['code'] == 'validation_error':
for issue in error.get('details', {}).get('issues', []):
print(f"Validation error in {issue['path']}: {issue['message']}")
else:
print(f"Error: {error['message']}")
Validation Error Details
When you receive a validation_error, the details.issues array contains specific validation failures:
{
"error": {
"code": "validation_error",
"message": "Validation failed",
"request_id": "req_7f8a9b0c1d2e3f4g",
"details": {
"issues": [
{
"path": "client_id",
"message": "Required"
}
]
}
}
}
| Header | Description |
|---|
X-Request-Id | Unique request ID for debugging and support |
