Error codes & handling

Both APIs return predictable JSON errors. The envelopes differ between the REST API and the Mobile API — parse the right one.

Who this is for#

• Developer — writing retry/backoff logic or mapping errors to user messages.
• Support — reading an integration's logs and telling apart auth, scope and quota problems.

Prerequisites: basic familiarity with HTTP status codes.

The two envelopes#

REST API (/api/v1/*)#

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": { "first_name": ["The first name field is required."] }
}

• status is always "error" on failure.
• code is a stable machine-readable token (table below).
• errors appears only on 422 validation failures.

Mobile API (/api/v1/mobile/*)#

{ "error": { "message": "Invalid email or password.", "code": "INVALID_CREDENTIALS" } }

• Success is {"data": ...}; failure is {"error": {"message", "code"}}.
• A few mobile endpoints have their own minimal shapes (for example the capability push returns a literal {"ok":true}) — the endpoint docs flag these.

Status codes at a glance#

REST API codes in detail#

Defined in App\Http\Responses\ApiErrorResponse:

A real 422 example#

Creating a lead without first_name (required):

curl -s -X POST "https://crm.zodiactechsoft.in/api/v1/leads" \
  -H "Authorization: Bearer lh_yourKeyHere" \
  -H "Content-Type: application/json" \
  -d '{"email":"lead@example.com"}'

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "first_name": ["The first name field is required."]
  }
}

Mobile API codes in detail#

Handling 429 correctly#

1. Read Retry-After (seconds) and sleep at least that long.
2. Back off exponentially for repeated hits.
3. If your workload legitimately needs more, raise the key's rate_limit_per_hour (up to 100000) — but remember the workspace ceiling is a multiple of the per-key limit.

Common mistakes#

• Retrying 4xx errors without changes — only 429 and 5xx deserve retries.
• Ignoring the errors map on 422 and showing only the generic message.
• Treating a 404 on a cross-workspace id as a bug — it is intentional isolation.
• Parsing the wrong envelope (e.g. expecting {"status":"error"} from the mobile API).

Troubleshooting#

Technical details#

• REST error builder: App\Http\Responses\ApiErrorResponse (UNAUTHORIZED, FORBIDDEN, NOT_FOUND, RATE_LIMITED, VALIDATION_FAILED, SERVER_ERROR; quota helper emits 402 LEAD_LIMIT_REACHED).
• Mobile login codes: App\Http\Controllers\Api\Mobile\AuthController.
• Unhandled API exceptions are rendered with the same error shape by the framework's JSON exception handling (Accept: application/json required).
• Rate-limit headers and messages: App\Http\Middleware\ApiKeyAuthentication.

Related guides#

• Authentication
• REST API (API keys)
• Mobile API (device tokens)
• Webhook endpoints