Skip to main content

​
Errors

Docyard uses standard HTTP status codes and returns structured error responses.

​
Error Response Format

All errors follow this structure: 
{
  "error": "error_code",
  "message": "Human-readable description",
  "details": { ... },
  "request_id": "req-abc123xyz"
}
FieldDescriptionExample
errorMachine-readable error codevalidation_error
messageHuman-readable description”The policy_number field is required”
detailsAdditional context (when applicable){ "field": "policy_number" }
request_idUnique request identifierreq-abc123xyz

​
HTTP Status Codes

Status CodeMeaning
200Success
201Created
204No Content
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Conflict
422Validation Error
429Rate Limited
500Internal Server Error

​
Authentication Errors

​
authentication_required

Status: 401 
{
  "error": "authentication_required",
  "message": "API key and secret are required",
  "request_id": "req-abc123xyz"
}
Solution: Include X-API-Key and X-API-Secret headers.

​
invalid_api_key

Status: 401 
{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid",
  "request_id": "req-abc123xyz"
}
Solution: Check that you’re using the correct API key.

​
invalid_api_secret

Status: 401 
{
  "error": "invalid_api_secret",
  "message": "The provided API secret is incorrect",
  "request_id": "req-abc123xyz"
}
Solution: Check that you’re using the correct API secret.

​
api_key_expired

Status: 401 
{
  "error": "api_key_expired",
  "message": "The API key has expired. Please rotate your keys.",
  "request_id": "req-abc123xyz"
}
Solution: Rotate your API keys.

​
Validation Errors

​
validation_error

Status: 422 
{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "field": "locks.policy_number",
    "issue": "required"
  },
  "request_id": "req-abc123xyz"
}
Solution: Fix the validation issue and retry.

​
invalid_data_type

Status: 422 
{
  "error": "validation_error",
  "message": "Invalid data type for field",
  "details": {
    "field": "locks.effective_date",
    "expected": "date",
    "received": "string"
  },
  "request_id": "req-abc123xyz"
}
Solution: Ensure the field value matches the expected data type.

​
invalid_format

Status: 422 
{
  "error": "validation_error",
  "message": "Field does not match required format",
  "details": {
    "field": "locks.policy_number",
    "pattern": "^POL-[0-9]{8}$"
  },
  "request_id": "req-abc123xyz"
}
Solution: Ensure the value matches the validation pattern.

​
Access Errors

​
access_denied

Status: 403 
{
  "error": "access_denied",
  "message": "You do not have permission to perform this action",
  "request_id": "req-abc123xyz"
}
Solution: Ensure you’re using the correct credentials for your role.

​
insufficient_score

Status: 403 
{
  "error": "insufficient_score",
  "message": "Score (5) is below threshold (20)",
  "details": {
    "score": 5,
    "threshold": 20,
    "keys_provided": ["mortgagee_name"]
  },
  "request_id": "req-abc123xyz"
}
Solution: Provide additional keys to meet the threshold.

​
unauthorized_lock_type

Status: 403 
{
  "error": "unauthorized_lock_type",
  "message": "You are not authorized to use the 'tax_id' lock type",
  "request_id": "req-abc123xyz"
}
Solution: Request permission for this lock type from Docyard admin.

​
Resource Errors

​
not_found

Status: 404 
{
  "error": "not_found",
  "message": "Artifact not found",
  "details": {
    "resource_type": "artifact",
    "resource_id": "art-nonexistent"
  },
  "request_id": "req-abc123xyz"
}
Solution: Verify the resource ID exists.

​
template_not_found

Status: 404 
{
  "error": "template_not_found",
  "message": "Template not found or not published",
  "details": {
    "template_id": "tmpl-nonexistent"
  },
  "request_id": "req-abc123xyz"
}
Solution: Use a published template ID.

​
artifact_revoked

Status: 410 
{
  "error": "artifact_revoked",
  "message": "This artifact has been revoked by the distributor",
  "request_id": "req-abc123xyz"
}
Solution: Contact the distributor for re-upload.

​
Rate Limiting

​
rate_limit_exceeded

Status: 429 
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 60 seconds.",
  "details": {
    "retry_after": 60,
    "limit": 100,
    "window": "60 seconds"
  },
  "request_id": "req-abc123xyz"
}
Solution: Wait and retry after the specified time.

​
Server Errors

​
internal_error

Status: 500 
{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again.",
  "request_id": "req-abc123xyz"
}
Solution: Retry the request. If the issue persists, contact support with the request_id.

​
service_unavailable

Status: 503 
{
  "error": "service_unavailable",
  "message": "Service temporarily unavailable. Please try again later.",
  "request_id": "req-abc123xyz"
}
Solution: Retry after a few minutes.

​
Error Handling Best Practices

​
1. Always Check Status Codes

const response = await client.ramp.upload(data);

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

// Success
processResult(response.data);

​
2. Log Request IDs

Always include request_id when contacting support: 
catch (error) {
  console.error('Docyard Error:', {
    error: error.error,
    message: error.message,
    requestId: error.request_id
  });
}

​
3. Implement Retry Logic

For transient errors: 
async function uploadWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.ramp.upload(data);
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        await sleep(1000 * (i + 1)); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

​
4. Handle Validation Errors Gracefully

const response = await client.ramp.upload(data);

if (response.status === 422) {
  const { details } = await response.json();
  
  if (details.field) {
    showFieldError(details.field, details.issue);
  }
}

​
Contacting Support

When contacting support, always include:
  1. Request ID: Found in every error response
  2. Endpoint: The API endpoint you were calling
  3. Timestamp: When the error occurred
  4. Request payload: (Remove sensitive data)
Email: [email protected]

​
Next Steps