Errors & status codes

The Diggama API uses standard HTTP status codes and returns JSON error responses.

Success codes

Status	Description	Used by
200 OK	Request succeeded	GET, PUT, PATCH, bulk update/delete/publish/unpublish
201 Created	Resource created	POST, bulk create when every item succeeds
204 No Content	Resource deleted	DELETE
207 Multi-Status	Some items failed	Bulk create only

Error response format

Every V2 error returns an error object:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "details": [],
    "timestamp": "2026-02-07T12:00:00+00:00",
    "request_id": "9b2f4c1e-6a7d-4f3b-8e21-0c5d9a7b1f42"
  }
}

Key	Description
code	Stable, machine-readable error code (see below)
message	Human-readable explanation
details	Extra data: field errors for VALIDATION_ERROR, retry_after for RATE_LIMIT_EXCEEDED; an empty array otherwise
timestamp	When the error occurred (ISO 8601)
request_id	The value of your X-Request-ID request header, or a generated UUID if you didn't send one. Quote it when contacting support

TIP

Send your own X-Request-ID header to correlate API errors with your logs.

Validation errors (422)

Validation errors use the code VALIDATION_ERROR, with messages keyed by field under error.details. Keys are prefixed with attributes. when you send the nested format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "attributes.email": ["The attributes.email field must be a valid email address."],
      "attributes.title": ["The attributes.title field is required."]
    },
    "timestamp": "2026-02-07T12:00:00+00:00",
    "request_id": "9b2f4c1e-6a7d-4f3b-8e21-0c5d9a7b1f42"
  }
}

Error codes

Status	Code	Common cause
400	BULK_LIMIT_EXCEEDED	More than 100 IDs sent to bulk delete, publish or unpublish
401	UNAUTHENTICATED	No Authorization header, or an invalid, expired or revoked token
403	FORBIDDEN	Token lacks the required ability for this blueprint
404	RESOURCE_NOT_FOUND	Unknown blueprint slug, unknown or malformed resource ID, or a resource from another blueprint or project
422	VALIDATION_ERROR	Invalid field values (wrong type, missing required field, reference to a resource that doesn't exist), or more than 100 items in bulk create/update
422	INVALID_FILTER	Unknown filter field or operator. See Filtering
422	UNPROCESSABLE_ENTITY	Request understood but refused, e.g. an export over 10,000 rows
429	RATE_LIMIT_EXCEEDED	Too many requests. See Rate limits
other 4xx	HTTP_ERROR	Any other HTTP error, e.g. 405 for an unsupported method
500	INTERNAL_ERROR	Unexpected server error

BULK_LIMIT_EXCEEDED

This error is returned directly by the bulk endpoints and only carries code and message: no details, timestamp or request_id.

Rate limits

Each project may make 1,000 requests per minute. The limit is per project, not per token: every token of the project shares the same budget, across V1 and V2.

Responses carry the current state of the budget:

Header	Description
X-RateLimit-Limit	Requests allowed per minute (1000)
X-RateLimit-Remaining	Requests left in the current window

When the limit is exceeded, the API returns 429 with the number of seconds to wait in error.details.retry_after:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "details": {
      "retry_after": 42
    },
    "timestamp": "2026-02-07T12:00:00+00:00",
    "request_id": "9b2f4c1e-6a7d-4f3b-8e21-0c5d9a7b1f42"
  }
}

API v1

The deprecated V1 endpoints do not use this format. They return Laravel's default body: {"message": "..."}, plus an errors object keyed by field on 422.

Troubleshooting

"Unauthenticated" (401)

• Verify the token is passed as Authorization: Bearer {token}
• Check that the token has not expired, been revoked or been regenerated in the dashboard
• Ensure you're using the correct project token

"Forbidden" (403)

• The token exists but lacks the required ability. Check the token's permissions in Settings › API Tokens
• Abilities are scoped per blueprint: a token with view on posts cannot access products

"Not Found" (404)

• Verify the blueprint slug matches exactly (e.g. blog-posts, not blogposts)
• Check the resource ID is correct and belongs to the same blueprint and project as the token
• A view-only token cannot see drafts or scheduled resources

"Unprocessable Entity" (422)

• Read error.details to identify which fields failed validation
• Ensure field values match the expected types defined in the blueprint
• For reference fields, ensure the referenced resource ID exists
• For INVALID_FILTER, the message lists the fields you can filter on