---
title: "Error Codes Reference | DreamFactory Docs"
source: "https://docs.dreamfactory.com/api-reference/error-codes"
canonical_url: "https://docs.dreamfactory.com/api-reference/error-codes"
converted_at: "2026-04-05T13:49:57.664Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
HTTP status codes and exception classes returned by DreamFactory APIs.

## Error Response Format[​](#error-response-format)

All errors return a consistent JSON structure:

```
{  "error": {    "code": 400,    "message": "Bad Request",    "context": {      "field": "email",      "error": "Invalid email format"    }  }}
```

---

## Client Errors (4xx)[​](#client-errors-4xx)

### 400 Bad Request[​](#400-bad-request)

**Exception Class:** `BadRequestException`

The request is malformed or contains invalid data.

**Common Causes:**

- Invalid JSON in request body

- Missing required fields

- Invalid field values or types

- Malformed filter expression

**How to Fix:**

- Validate JSON syntax before sending

- Check required fields in documentation

- Verify data types match schema

**Example:**

```
{  "error": {    "code": 400,    "message": "Invalid JSON: Syntax error"  }}
```

---

### 400 Invalid JSON[​](#400-invalid-json)

**Exception Class:** `InvalidJsonException`

Request body contains malformed JSON.

**Common Causes:**

- Trailing commas in JSON

- Unquoted keys

- Single quotes instead of double quotes

- Unclosed brackets or braces

**How to Fix:**

```
# Validate JSON before sendingecho '{"name": "test"}' | jq .
```

---

### 400 Batch Error[​](#400-batch-error)

**Exception Class:** `BatchException`

One or more operations in a batch request failed.

**Response includes details for each failed operation:**

```
{  "error": {    "code": 400,    "message": "Batch operation error",    "context": {      "errors": [        {"index": 0, "message": "Duplicate key value"},        {"index": 2, "message": "Foreign key violation"}      ]    }  }}
```

**How to Fix:**

- Review individual error messages

- Fix problematic records and retry

---

### 401 Unauthorized[​](#401-unauthorized)

**Exception Class:** `UnauthorizedException`

Authentication required or credentials invalid.

**Common Causes:**

- Missing API key or session token

- Expired session token

- Invalid API key

- API key not associated with an app

**How to Fix:**

- Include `X-DreamFactory-API-Key` header

- Or include `X-DreamFactory-Session-Token` header

- Refresh expired sessions via `/api/v2/user/session`

**Example Request (correct):**

```
curl -X GET "https://example.com/api/v2/db/_table/contacts" \  -H "X-DreamFactory-API-Key: your-api-key"
```

---

### 403 Forbidden[​](#403-forbidden)

**Exception Class:** `ForbiddenException`

Authenticated but not authorized for this action.

**Common Causes:**

- Role lacks permission for this service

- Role lacks permission for this table/endpoint

- Role lacks permission for this HTTP method

- Trying to access admin endpoints as non-admin

**How to Fix:**

- Check role permissions in admin panel

- Verify service access is granted to role

- Confirm HTTP method is allowed

---

### 404 Not Found[​](#404-not-found)

**Exception Class:** `NotFoundException`

Resource does not exist.

**Common Causes:**

- Table does not exist

- Record with given ID not found

- Service name is incorrect

- Stored procedure/function does not exist

**How to Fix:**

- Verify table name: `GET /api/v2/{service}/_schema`

- Verify record exists before update/delete

- Check service name in system config

---

### 409 Conflict[​](#409-conflict)

**Exception Class:** `ConflictResourceException`

Resource state conflict.

**Common Causes:**

- Duplicate primary key

- Unique constraint violation

- Foreign key constraint violation

- Concurrent modification conflict

**How to Fix:**

- Check for existing records before insert

- Use upsert if `allow_upsert` is enabled

- Verify foreign key references exist

**Example:**

```
{  "error": {    "code": 409,    "message": "Duplicate entry '[email protected]' for key 'email'"  }}
```

---

### 429 Too Many Requests[​](#429-too-many-requests)

**Exception Class:** `TooManyRequestsException`

Rate limit exceeded.

**Common Causes:**

- Too many API calls in time window

- Service-level rate limit reached

- User-level rate limit reached

**How to Fix:**

- Implement exponential backoff

- Check `Retry-After` header for wait time

- Batch operations where possible

- Request rate limit increase if needed

**Response Headers:**

```
Retry-After: 60X-RateLimit-Limit: 1000X-RateLimit-Remaining: 0X-RateLimit-Reset: 1707700800
```

---

## Server Errors (5xx)[​](#server-errors-5xx)

### 500 Internal Server Error[​](#500-internal-server-error)

**Exception Class:** `InternalServerErrorException`

Unexpected server-side error.

**Common Causes:**

- Database connection failure

- Script execution error

- Configuration error

- Unhandled exception in service logic

**How to Fix:**

- Check server logs for details

- Verify database connectivity

- Review recent configuration changes

- Contact administrator if persistent

---

### 501 Not Implemented[​](#501-not-implemented)

**Exception Class:** `NotImplementedException`

Feature or endpoint not available.

**Common Causes:**

- Requested feature not supported by this database type

- API version mismatch

- Service type does not support this operation

**How to Fix:**

- Check documentation for supported features

- Use alternative approach if available

---

### 503 Service Unavailable[​](#503-service-unavailable)

**Exception Class:** `ServiceUnavailableException`

Service temporarily unavailable.

**Common Causes:**

- Database server down

- External service unreachable

- Maintenance mode enabled

- Resource exhaustion (connections, memory)

**How to Fix:**

- Retry with exponential backoff

- Check service health status

- Verify external service availability

---

## Error Handling Best Practices[​](#error-handling-best-practices)

### 1. Always Check Status Codes[​](#1-always-check-status-codes)

```
const response = await fetch(url, options);if (!response.ok) {  const error = await response.json();  console.error(`Error ${error.error.code}: ${error.error.message}`);}
```

### 2. Implement Retry Logic[​](#2-implement-retry-logic)

```
async function fetchWithRetry(url, options, maxRetries = 3) {  for (let i = 0; i < maxRetries; i++) {    const response = await fetch(url, options);    if (response.status === 429) {      const retryAfter = response.headers.get('Retry-After') || 60;      await sleep(retryAfter * 1000);      continue;    }    if (response.status >= 500) {      await sleep(Math.pow(2, i) * 1000);      continue;    }    return response;  }  throw new Error('Max retries exceeded');}
```

### 3. Log Context for Debugging[​](#3-log-context-for-debugging)

Include request details when logging errors:

- Request URL and method

- Request body (sanitized)

- Response status and body

- Timestamp

---

## Quick Reference Table[​](#quick-reference-table)

CodeException ClassMeaningAction400BadRequestExceptionInvalid requestFix request format400InvalidJsonExceptionMalformed JSONValidate JSON400BatchExceptionBatch partial failureCheck individual errors401UnauthorizedExceptionAuth requiredAdd API key/token403ForbiddenExceptionAccess deniedCheck role permissions404NotFoundExceptionNot foundVerify resource exists409ConflictResourceExceptionConflictHandle duplicates429TooManyRequestsExceptionRate limitedBackoff and retry500InternalServerErrorExceptionServer errorCheck logs501NotImplementedExceptionNot supportedUse alternative503ServiceUnavailableExceptionUnavailableRetry later

---

## See Also[​](#see-also)

- [API Endpoints](/api-reference/api-endpoints) - Complete endpoint reference

- [Query Parameters](/api-reference/query-parameters) - Filter and pagination