Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Error Handling

The API uses standard HTTP status codes and returns consistent JSON error bodies for all failure cases.

​
HTTP status codes

CodeMeaningCommon cause
200OKRequest succeeded
201CreatedResource was created
204No ContentResource was deleted
400Bad RequestMalformed request body
401UnauthorizedMissing or invalid Authorization header
403ForbiddenToken valid but insufficient permissions
404Not FoundResource does not exist or belongs to another tenant
422Unprocessable EntityValidation failed (see errors field)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server error

​
Error response body

All error responses return a JSON body with success: false. The structure varies by error type.

​
Validation error (422)

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required.", "The email must be a valid email address."],
    "course_uuid": ["The selected course uuid is invalid."]
  }
}
The errors object maps field names to an array of human-readable messages.

​
Authentication error (401)

{
  "success": false,
  "message": "Unauthenticated."
}

​
Not found (404)

{
  "success": false,
  "message": "Resource not found."
}

​
Generic server error (500)

{
  "success": false,
  "message": "Server Error"
}

​
Handling errors in code

async function createCertificate(payload) {
  const response = await fetch('https://api.dokstamp.com/certificates', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'X-Tenant': TENANT,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const error = await response.json();

    if (response.status === 422) {
      // Validation error — inspect error.errors for field-level detail
      console.error('Validation failed:', error.errors);
    } else if (response.status === 401) {
      // Token expired or missing — request a new service token
      await renewToken();
    } else {
      throw new Error(error.message);
    }
  }

  return response.json();
}

​
Common mistakes

Returns 401 or 404 depending on the endpoint. Always include X-Tenant on resource endpoints.
When creating a certificate, the file_uuid must reference a file that has not yet been attached to another certificate. Once a file is used, it cannot be reused.
All UUID fields must be in standard v4 format: 550e8400-e29b-41d4-a716-446655440000. Passing an integer where a UUID is expected returns 422.
If you pass a course_uuid or student_uuid that belongs to a different tenant, the API returns 422 with "The selected ... is invalid." — the entity lookup is always tenant-scoped.