Error Handling

All JSON API responses on api.wedocod.com use one of two root shapes: success (data + meta) or error (error).

Success envelope

{
  "data": {},
  "meta": {}
}

• data: endpoint payload — object, array, or scalar. For a single resource returned as a Laravel API resource, the resource fields appear under data.
• meta: optional metadata. Always present as an object; may be empty ({}). Common keys:
  • pagination — list endpoints: page, limit, total, pages
  • mode — bulk create: sync or async
  • total — number of items in the bulk request
  • updated_fields — fields applied in a bulk update

Paginated list (200)

{
  "data": [
    {
      "reference": "LED-00001",
      "phone": "0612345678",
      "status": "new"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 120,
      "pages": 3
    }
  }
}

Query parameters: page, per_page, plus resource-specific filters (see each endpoint).

Bulk create — sync (201)

When the batch size is within the sync threshold (≤ 10 items by default), processing completes in the same request:

{
  "data": {
    "created_refs": ["WDKJHGFHJKL"],
    "failed_count": 0
  },
  "meta": {
    "mode": "sync",
    "total": 1
  }
}

Bulk create — async (202)

Larger batches are queued; use webhooks or poll your integration for completion:

{
  "data": {
    "batch_id": "batch_550e8400-e29b-41d4-a716-446655440000",
    "queued": true
  },
  "meta": {
    "mode": "async",
    "total": 25
  }
}

Bulk update (200)

{
  "data": [
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "reference": "LED-00001"
    }
  ],
  "meta": {
    "updated_fields": ["status"]
  }
}

Delete (200)

{
  "data": {
    "deleted": true,
    "count": 2
  },
  "meta": {}
}

Error envelope

{
  "error": {
    "code": "MACHINE_READABLE_CODE",
    "message": "Human-readable explanation"
  }
}

Optional keys on error:

Key	When
fields	Validation (422) — Laravel field => message arrays
batch	Legacy bulk failure details (if returned by an endpoint)
retry_after	Rate limiting (429), when provided

Error codes

Code	Typical HTTP status
VALIDATION_ERROR	422
UNAUTHENTICATED	401
NOT_FOUND	404
HTTP_ERROR	403, 429, 5xx, and other HTTP exceptions

Validation (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "fields": {
      "phone": [
        "The phone field is required."
      ],
      "data.0.phone": [
        "The phone field is required."
      ]
    }
  }
}

HTTP status codes

Code	Meaning
200	Success
201	Resource created (including sync bulk create)
202	Accepted — async bulk processing queued
401	Unauthenticated — token missing or invalid
403	Forbidden — insufficient permissions
404	Resource not found
422	Validation failed
429	Rate limit exceeded
500	Server error

Unauthenticated (401)

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Unauthenticated."
  }
}

Not found (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found."
  }
}

Forbidden (403)

{
  "error": {
    "code": "HTTP_ERROR",
    "message": "This action is unauthorized."
  }
}

Rate limit (429)

{
  "error": {
    "code": "HTTP_ERROR",
    "message": "Too Many Attempts."
  }
}

Bulk operations (leads / orders)

• Validation (422) — field keys may look like data.2.full_name or leads.0.status.
• Sync bulk — partial row failures increment failed_count; see data.created_refs and integration webhooks for async batches.
• Rows that throw during sync processing are summarized in webhooks for async mode (meta.mode: async).